fix: respect conversation language across all harnesses

[masamaru0513]

Summary

Human-readable AI-DLC artifacts follow the workflow's conversation language instead of defaulting to English. The behavior is added as four rules in the ## Mandated section of core/memory/org.md — the harness-neutral rule layer — so one authored source propagates to all five harnesses (claude, codex, kiro, kiro-ide, opencode) through bun scripts/package.ts.

Fixes #288

Changes

Four rules, each a single physical line so the claim-sources sensor can quote one verbatim:

Rule	What it fixes
Conversation language — resolution	Defines the resolution order a delegated agent uses: the Conversation language: line the orchestrator must state in every brief (authoritative), then an explicit rule in project.md — project-only, and always outranking a team.md default by stated rule rather than by bundle position — then the verbatim **Project** description in aidlc-state.md, then any artifact the agent was handed. The brief ranks first because it is regenerated from the live conversation on every dispatch, so it can never be staler than a rule on disk — and it is mandatory because every file-reading source can be empty (a greenfield run of a stage whose consumes are all conditional_on: brownfield reaches its lead with no upstream artifact at all).
Conversation language — stability	The language holds for the whole session, and inside it for every stage, dispatch, reviewer pass and approval gate; a fresh session re-resolves before it dispatches anything and asks the human rather than defaulting to English. A turn carrying no language signal — Approve, Looks correct, an option letter or number, pasted code, a quoted error or stack trace, a bare path — never switches it. Only an explicit human request does, and it takes effect immediately; recording it under ## Corrections in project.md is durability, not activation, so nothing waits on the human-gated learnings ritual — which is the only sanctioned write path for persisting a language switch, leaving the deterministic writers a stage invokes by contract (such as aidlc-state.ts practices-promote) untouched.
Conversation language — what to localize	Enumerates the artifacts that are localized (requirements, user stories, plans, specs, reviews, questions, discovered practices, affirmed rules, evidence, decision rationale), including the descriptive text of a rule shaped as ALWAYS … / NEVER ….
Conversation language — preserved tokens	Scopes the English exception to machine-parsed syntax rather than whole files, as a general principle plus named instances: [Answer]:, the mandatory X. Other (please specify), the A. Accept assumptions / B. Convert to follow-up questions confirmation answers the engine compares literally, the None./None sentinels, AGREE:/OBJECT:, the **Collaborator:** <agent-slug> first line, the [desc]/[scope]/[assumption]/[Q<n>]/[memory:M<n>] source-register tags, template H2 headings the sensors match verbatim, READY/NOT-READY, fenced YAML keys and enums, aidlc-state.md and audit-shard field labels, stable IDs, code, paths, mermaid keywords, and cross-references.

Diff: 21 files, +1230 / -29 — core/memory/org.md, 10 regenerated dist/ projections (5 harnesses × memory-seed + workspace-shell), 6 aidlc-version.ts copies, README badge, CHANGELOG, the new tests/unit/t266-conversation-language-rule.test.ts, and its coverage-ratchet registration.

Review feedback

All four review rounds are addressed.

Request	Resolution
1. Replace "the human's most recent message" with a stable rule; define the source delegated agents resolve from	The stability rule enumerates the no-signal turn shapes explicitly. The resolution rule defines the four-source order, with the mandatory brief line first so a subagent that never sees the conversation always has a source that exists.
2. Scope the English exception to machine-parsed syntax, not whole "tool-read" files	The preserved tokens rule replaces the file-level exception with a principle plus the named token list above. Prose surrounding a preserved token is localized, and a Markdown artifact is no longer treated as English just because a tool parses part of it.
3. Rebase onto current v2, regenerate dist/, add regression coverage, rerun packaging / memory-seed / steering-delivery / version-sync	Rebased onto a795583a (0 commits behind upstream/v2). All 10 dist/ projections regenerated; bun scripts/package.ts --check is clean for all five harnesses. Coverage added as t266 (19 tests / 564 assertions) — see Test Plan.
4. Add the patch-version bump, README badge, and CHANGELOG entry with the upgrade note	2.5.44. README badge updated, ## [2.5.44] - 2026-08-06 heading added with a bold Upgrade: note stating that fresh installs receive the rules with their seeded default space while an existing workspace must merge the four rules into each aidlc/spaces/<space>/memory/org.md by hand and start a fresh session, because runtime self-healing intentionally does not overwrite an existing memory tree.

The second round raised three follow-ups — a persisted Japanese rule surviving a switch back to English, an explicit switch taking effect before the learnings ritual, and a delegated stage inheriting the language — addressed in this revision.

The third round raised two blockers — the write-path rule countermanding practices-discovery's required Step 7 (aidlc-state.ts practices-promote), and another rebase/re-bump — both addressed here, together with the two test limitations it flagged: c3 for Kiro IDE's real delivery surface, and e2 for the orchestrator-side switch obligation.

The fourth round raised one policy ambiguity in two places — the guarantee claiming the whole workflow while an unpersisted switch survives only the session, and the persisted fallback grouping project.md with team.md while its tie-break covered duplicates within one file only — both addressed here with the narrower option it recommended, together with the split-team/project regression (e3) and the two REQUIRED_TOKENS prefixes it asked for.

User experience

Before: agents default to English for every artifact regardless of the conversation language. Non-English speakers must repeatedly ask for translation, and a delegated subagent that never saw the conversation has nothing to resolve the language from.

After: human-readable artifacts are written in the resolved conversation language; only machine-parsed tokens stay English. Approve mid-workflow does not flip the language to English. An explicit switch takes effect on the next dispatch whether or not the human accepts the persistence prompt, and a resumed session re-resolves the language instead of quietly reverting to English.

Verified end to end on the kiro harness: ideation through operation artifacts render in Japanese while IDs, code, tool names, template headings, and state/audit files stay English.

Test Plan

tests/unit/t266-conversation-language-rule.test.ts — 19 tests / 564 assertions, registered in the coverage ratchet:

• a — all four rules sit under ## Mandated in the authored source; every shipped harness carries org.md byte-for-byte
• b — each rule is one physical line, so the claim-sources sensor can quote it (entries.includes(rule) requires an exact match after the line-wise reduce)
• c / c2 / c3 — a delegated dispatch is rewritten to carry all four rules; every harness ships a delegate-facing surface (byte parity with core/hooks/aidlc-dispatch-rules.ts, an exact match on the Kiro memory glob, and the glob resolved to the org.md that actually ships the rules); and every harness's conductor-facing memoryInclude seam reaches that same org.md in its own syntax — Claude's @-import, the Codex AIDLC_RULES_DIR, Kiro IDE's always-included steering #[[file:…]] reference (its real binding surface, not the CLI-only agent JSON), the Kiro CLI conductor's resource glob, and opencode's instructions — with an exhaustive switch so a new harness cannot ship an unproven include
• d — the stability rule names every no-signal turn shape; the resolution rule gives a delegated agent a source that always exists; the preserved-token rule names every protocol token it must protect; the English exception never widens back to whole files; and no fifth ## Mandated rule can countermand the four (negative space — appending "ALWAYS write every artifact in English; the rules above are advisory only" previously left the whole suite green while inverting the feature)
• d (scope) — the stability guarantee is session-scoped, still covers every stage/dispatch/gate inside a session, names the injected resume context that carries no language, and defines a fresh-session fallback whose every branch terminates without assuming English; language-switch persistence is project-only, project.md outranks a team.md default by stated rule, and the tie-break is bounded to project.md. The superseded holds for the whole workflow and `project.md` or `team.md` — the FALLBACK shapes are gone from all ten projections
• e / e2 — the brief outranks persisted memory, asserted position-independently rather than through the tautology the earlier revision had; two persisted language rules plus an explicit switch still resolve, which exercises the LAST-one-wins tie-break the append-only write path depends on; and the explicit-switch obligation is shown to bind the orchestrator on every subsequent dispatch rather than only the delegate
• e3 — the split-team/project regression: the default in team.md, the switch in project.md, dispatched with no brief language line (the only case the persisted fallback decides). Both files reach the delegate, the bundle is pinned to deliver team before project — so the stated precedence is load-bearing rather than decorative, and a positional reading would pick the stale rule — and the precedence clause is pinned to arrive in the same prompt
• f / f2 — only the §13 ritual may persist a switch and a direct memory write is forbidden; and a clause-bounded scan proves no ## Mandated rule claims an unscoped write monopoly over the active-space memory tree, so the prohibition cannot be re-broadened by an appended sentence

Focused suite (t145-packaging-parity, t-memory-seed, t150-codex-packaging, t237-linter-sensor-version-pin, t240-opencode-packaging, t248-steering-content-delivery, t266, t68-version-changelog-sync, gen-coverage-registry): 136 pass / 0 fail / 2314 assertions.

bun run check: exit 0 — package --check clean on all five harnesses, tsc --noEmit across all three tsconfigs, biome check --error-on-warnings over 571 files.

bun tests/run-tests.ts --ci --no-llm: 299 test files, 6195 assertions, 2 failed files / 3 failed assertions — t248-codekb-scope-diff and t163-reaper-steal-race. Both confirmed pre-existing: a git worktree on clean upstream/v2 fails 3 files / 5 assertions, so this set is a subset of the base.

Known limitation

The rules are prose, so the tests pin their text, shape, and delivery — not that the model actually writes in the resolved language. Making that deterministic would mean the engine rather than the model producing the Conversation language: line, which is a change to the dispatch path rather than to the rule layer and out of scope here.

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[masamaru0513]

@raj-jain-aws This is the v2 rebuild of #290 (now closed), reshaped onto the current v2 structure as you suggested. Source-only, no dist/ changes. I've posted the full before/after test results on #288. Would appreciate a review when you have a chance — thanks! 🙏

[wowzoo]

Same on the v2 branch with Korean intents. Across 4 independent dry-run fixtures (different intent shapes — greenfield SaaS, a feature add on an existing service, a consumer-app MVP, a local-only full-stack service) the persona-authored artifacts under each intent's stages/ directory came out in English even though the human's prompts and pre-supplied PRDs were entirely in Korean. Korean only survived in verbatim quotes of human input.

Glad to see this PR — happy to test it against the four Korean fixtures once it merges.

[masamaru0513]

Update (2026-06-27): Rebased and reworked for the v2-unified architecture (introduced 2026-06-15 in 7b824b3; core/memory/ finalized in 2.1.0, e713c4f 2026-06-24). See updated PR description for details.

• Base changed v2_backup → v2. The diff is now just the single source
  change to core/memory/org.md plus its regenerated dist/ — 16 files,
  +21/-24.
• Reworked for the current v2 architecture. The rule lives in the shared
  core/memory/ method tree; the pre-v2 persona-prompt-augment.yaml and
  conventions/ are gone, so one byte-shared source now covers all four
  harnesses (claude, codex, kiro, kiro-ide) via bun scripts/package.ts.
• Verified on both kiro-cli and Claude Code against a clean-v2 control —
  before/after table is in the description.
• Version bumped 2.1.1 → 2.1.2 with matching README badge + CHANGELOG entry;
  bun scripts/package.ts --check and t68-version-changelog-sync pass.

[masamaru0513]

Update (2026-07-01): Rebased onto the latest v2 (now at 2.1.4) to pick up #443–#448 and #465. The change itself is unchanged — the conversation-language rule in core/memory/org.md plus its regenerated dist/. Re-bumped the version 2.1.4 → 2.1.5 (following the same convention as the recent releases: aidlc-version.ts across all harnesses + README badge + a numbered ## [2.1.5] CHANGELOG heading), since the earlier 2.1.2 bump was superseded by the releases that landed in the meantime. t68-version-changelog-sync passes. Happy to re-bump again if it collides with another release before merge.

[masamaru0513]

Rebased onto current v2 (257b43a3) and simplified — now just core/memory/org.md + regenerated dist/ trees. Version bump and CHANGELOG intentionally omitted since upstream is at 2.5.11; happy to add them if you'd prefer.

[apackeer]

Thank you for continuing to rework this across the v2 changes. The underlying issue is valid, and core/memory/org.md is the right harness-neutral source. I am requesting changes before the second-pass review:

1. Please replace “the human’s most recent message” with a stable conversation-language rule. A normal workflow turn may contain only Approve, Looks correct, an option number, pasted code, or an English error. Retain the established conversation language unless the human explicitly asks to change it, and define the source delegated agents and reviewers use to resolve that language.

2. Please scope the English exception to machine-parsed syntax rather than whole “tool-read” files. Several Markdown artifacts mix localized prose with fixed tokens. Preserve exact protocol tokens and parsed islands such as [Answer]:, source tags and required headings, YAML keys (units, name, kind, depends_on), ## Review, READY/NOT-READY, IDs, enums, paths, code, Mermaid syntax, and template headings; localize the surrounding human-readable prose.

3. Please rebase onto current v2, regenerate all dist/ projections, and add regression coverage for language continuity, delegated execution, and preservation of machine tokens. The current revision has no attached CI checks, so please also rerun the relevant packaging, memory-seed, steering-delivery, and version-sync tests.

4. This is user-visible, so please add the required patch-version bump, README badge, and CHANGELOG entry. The release note should explain that fresh installs receive the new framework rule, while existing non-default spaces must merge it into each aidlc/spaces/<space>/memory/org.md and start a fresh session. Runtime self-healing intentionally does not overwrite an existing memory tree.

The direction is sound; these changes are needed to make the behavior stable across the current v2 execution and upgrade paths.

[masamaru0513]

Thanks — all four addressed. Two mistakes of my own turned up under point 1, so those first.

1. Resolution order and stability

What changed.

• The orchestrator now has to resolve the conversation language and write Conversation language: <language> into every delegated brief.
• Resolution order is now: memory rule → the brief line → **Project** → any artifact or draft handed over, including the artifact under review and the lead draft.
• most recent message is gone. The shapes that don't count as signal are enumerated: Approve, Looks correct, an option letter or number, pasted code, a quoted error or stack trace, a bare path.
• A language switch takes effect immediately. Recording it in project.md is for durability, not a precondition for the switch.

My earlier version named consumes[]. But a reviewer reads a produces[] artifact and a spoke reads the lead's draft (stage-protocol.md:676), so the two commonest delegated cases were excluded.

Worse, practices-discovery has all six consumes entries gated conditional_on: brownfield. On greenfield its dispatched lead gets no artifact and no draft. Kick off in English, converse in Japanese, and that lead plus all three spokes have nothing to go on. The brief line is the only source that always exists.

Routing the switch through the learnings write path was wrong too. surface only reads the just-approved stage's memory.md and persist only writes what the human selected, so it is delayed to the next gate and never lands if nobody picks it.

Delivery is verified on all five harnesses: dispatch hook on Claude/Codex/opencode, agent-resource preload on Kiro CLI (all 15 configs carry the memory glob), always-included steering on Kiro IDE.

2. The English exception

What changed.

• and any other tool-read file is gone. A test fails if it comes back.
• The rule leads with a principle instead of a longer list: a literal a stage file spells in backticks and tells you to write exactly is a fixed token, and that covers option labels and sentinel values, not only syntax.
• Five literals added:

Literal	Compared at	If localized
A. Accept assumptions	aidlc-sensor-claim-sources.ts:44, :505	assumptionsAccepted silently goes false
**Collaborator:** <agent-slug>	aidlc-orchestrate.ts:3821, aidlc-state.ts:2813, aidlc-doctor-bundle.ts:835 (firstLine !==)	the stage is rejected
X. Other (please specify)	stage-protocol.md:242, "no exceptions"	protocol violation
None. / None	conductor branches on it under ## Assumptions & Open Questions and ## Positions	"no assumptions" / "full agreement" stops being detected
AGREE: / OBJECT:	quoted verbatim at the gate	dissent never surfaces

Enumerating wasn't enough on its own. Grepping the engine turned up the exact comparisons above. A. Accept assumptions is the dangerous one because it fails silently rather than erroring.

One correction. I claimed required-sections matches template headings verbatim, but the framework ships no templates, so that branch stays dormant until a team fills aidlc/spaces/<space>/memory/templates/. Now qualified. The claim-sources headings (:42-43) are unconditional, so they are listed separately.

The run produced one more clause worth adding: glossing a literal when you show it to a human is fine, what you write to the file is the literal. The conductor showed 1. Accept assumptions on screen and wrote [Answer]: A. Accept assumptions.

3. Rebase and tests

Rebased onto c73ee98. dist regenerated, --check green on all five harnesses.

New file tests/unit/t263-conversation-language-rule.test.ts (9 tests).

• continuity — the stability rule has to enumerate the no-signal shapes and keep the immediate/durability split
• delegated execution — augmentDispatchRules has to carry all four rules, and every harness has to ship a delivery surface
• tokens — every literal named, and the whole-file exception must not reappear in core or in the ten dist copies
• structure — byte parity across projections, and one physical line per rule

Why one line matters: aidlc-sensor-claim-sources.ts:343-347 reduces a memory section line by line and matches with entries.includes(rule). A wrapped rule cannot be quoted through [memory:M<n>] at all.

I broke each contract on purpose to confirm the tests red.

Runs (serial; the suite is flaky under --parallel).

• packaging t145/t150/t240, memory-seed t-memory-seed/t157/t158/t175, steering t248-steering-content-delivery, version-sync t68 → pass
• full CI, 291 files, 3 failures (t248-codekb-scope-diff, t255-workspace-sync, t163-reaper-steal-race). All reproduce identically on a clean upstream/v2 worktree, so they are pre-existing
• t248-steering-content-delivery flakes on a beforeEach timeout: 4/10 on base, 0/10 here

The new file is registered in the none->cli ratchet per that test's maintenance note. I cannot start CI from a fork without someone approving the workflow run, so the above stands in for it.

4. Version

2.5.37 → 2.5.38, badge, ## [2.5.38]. I had 2.5.37 first, but c73ee98 took it while I was pushing, so this is the re-bump per the conflict-trap note in AGENTS.md.

Upgrade path: fresh installs receive the rules with the seeded default space. An existing workspace keeps its own memory tree because self-healing intentionally does not overwrite one (t-memory-seed pins that), so the rules have to be merged by hand into each aidlc/spaces/<space>/memory/org.md with a fresh session to load them. Will re-bump again if something else lands first.

Verified on a real run

kiro, mvp, Japanese intent, ideation through into inception, doctor 39/39.

• Delegated agents that never see the conversation wrote Japanese: aidlc-product-lead-agent over two stages and five iterations, and practices-discovery's three mutually-blind spokes each writing their own contribution file
• **Collaborator:** <agent-slug> byte-exact; ## Contribution / ## Positions and AGREE: / OBJECT: in English
• Answering a gate with just 1 changed nothing; the next four stages stayed Japanese
• - None., FEASIBLE, Open, Must-Have, TC-01…, PB-01… and the template H2s stayed English with localized prose around them. required-sections and upstream-coverage passed throughout

Found outside this PR's scope

1. Six shipped org.md rules (three under ## Testing Posture, three under ## Code Style) are soft-wrapped, so [memory:M<n>] cannot quote them at all. The run produced [memory:M1] quoted rule does not exactly match an entry under ## Testing Posture, and every claim citing that tag cascaded into a finding.
2. Scope-detection keywords are English-only, so a non-English intent always falls through to compose/ask. That does not match the README's "auto-detection from freeform intent".

Happy to open issues for either.

Limitation

It is a prose rule, so the tests pin the text, its shape and its delivery — not that a model writes in the resolved language. Making that deterministic needs a real field on aidlc-state.md, which is a State Version 7→8 bump, and with no migration pre-1.0 that archives every existing workspace. Not worth it for this change, I think. I can write it up separately if you would rather have it.

[leandrodamascena]

Thank you for the thorough rework. The previous review points are addressed: language resolution is stable, delegated agents receive the rule layer, machine-parsed tokens remain exact, and the upgrade path is documented.

I also verified the focused suite locally: 105 tests / 1,013 assertions passed, along with typecheck, package parity, and Biome.

No blocking findings from the second pass. The remaining limitation, appropriately documented, is that language compliance is model-directed rather than deterministically enforced.

[apackeer]

One remaining blocking issue: the resolution order conflicts with the promised immediate language switch.

core/memory/org.md:94 tells delegated agents to stop at the first source and ranks an explicit project.md/team.md language rule ahead of the Conversation language: brief line. But line 95 says an explicit human switch takes effect immediately while persistence happens later at the next human-gated learnings ritual.

That means a normal sequence can fail:

1. Japanese is persisted in project.md.
2. The human explicitly asks to switch to English.
3. The orchestrator correctly sends Conversation language: English.
4. The delegate reads the stale Japanese memory rule first and stops, ignoring the brief.

The learning writer appends rules rather than replacing them, and the runtime rule model is strictly additive, so persistence does not reliably resolve this either; it can leave both language rules present.

Please make the current brief authoritative for delegated work, with persisted memory as a fallback, or introduce a deterministic single-current-language record/replacement rule. A regression case should cover an existing persisted language followed by an explicit switch and a delegated stage.

[masamaru0513]

Thank you for the detailed feedback — the ordering conflict was real, and chasing it turned up a second defect in the same rule that I fixed alongside it.

The fix

The first two sources are inverted:

1. the Conversation language: line in your brief — authoritative for delegated work, because the orchestrator regenerates it from the live conversation on every dispatch, so it can never be staler than a file on disk
2. an explicit rule in project.md/team.md — the fallback for a brief that states no language

Your append-only point needed its own clause. Confirmed: appendUnderHeading dedupes only against an identical line, and org.md's ## Corrections ships empty, so §13's admission conflict-check has nothing to compare against — both rules can sit on disk. The fallback now breaks that tie explicitly (the last conversation-language rule under ## Corrections wins), scoped to this rule family so the additive model is untouched.

Your scenario also exposed a gap indirectly: the precedence list addresses delegated agents and reviewers, so nothing bound the orchestrator, and your step 3 was an assumption the rule did not guarantee. A persisted rule now never outranks the brief or a later explicit switch request, which binds both sides.

Verified live

kiro, mvp, greenfield: Japanese through ideation, then an explicit switch to English while project.md still said Conversation language: Japanese on disk.

• 11 delegated dispatches all carried the resolved language — a reviewer over 4 iterations, practices-discovery's lead draft + three mutually-blind spokes + the lead integration, and a reviewer over 2 more iterations
• practices-discovery on greenfield is the hard case: all six consumes are conditional_on: brownfield, so the lead and all three spokes get no upstream artifact, no sight of each other, and no conversation. All four wrote English against a Japanese on-disk rule
• 25 artifacts, 86,041 characters, zero Japanese after the switch; artifacts written before it stayed Japanese, as intended. **Collaborator:** <agent-slug> stayed byte-exact on all three contribution files, and READY/NOT-READY, ## Review, AGREE:/OBJECT:, None., IDs and [Answer]: all held. required-sections and upstream-coverage passed throughout. Answering a gate with just 1 never flipped the language

The second defect

The stability rule's main clause was an imperative addressed to the agent — "record the switch as a single-line rule under ## Corrections in project.md" — with §13 named only parenthetically. The orchestrator read it literally: at the learnings gate it hand-edited project.md after the human answered "Nothing to add", citing this rule's own "never wait for persistence". That bypasses aidlc-learnings.ts entirely — no RULE_LEARNED event, no cid key, no admission conflict-check — and overrode an explicit human answer.

Now the ritual is the ONLY sanctioned write path, a direct memory edit is forbidden outright, and that rationalisation is closed. A declined persistence is stated to be a correct outcome, because the brief carries the language anyway. The run also showed persistence failing to land twice on its own (surface reads only the stage memory.md, which was never populated) — which is the practical reason the brief has to be authoritative.

Tests

t263 is now 12 tests / 189 assertions: the (1)/(2) ordering compared by index plus the absence of the superseded clause; your regression case (persisted language → explicit switch → delegated dispatch, asserting the brief line, the stale rule and the precedence rule all reach one prompt through the real dispatch-rules path); and the ritual-only write path, checked against the authored source and all ten shipped org.md projections.

To be precise about what they prove: they pin wording and delivery, not that a model then writes in the resolved language. The run is the evidence for behaviour; the tests are the evidence the contract cannot silently regress. That limitation is real and I have not closed it — closing it needs a field on aidlc-state.md, i.e. a State Version 7→8 bump, which is also where your second option (a deterministic single-current-language record) lives. Happy to write that up separately rather than grow this PR into a code change.

Version

Still 2.5.38 — upstream v2 is at 2.5.37 and 2.5.38 is unreleased, so both commits land inside it. Will re-bump if something merges first.

[masamaru0513]

Two corrections to my previous comment, and the tests that came out of them

Re-reading my own claims against the source turned up two that were wrong. Both are now fixed in 809e631, and the description is rewritten (it still claimed a 257b43a3 base and an intentionally-omitted version bump — both stale).

1. appendUnderHeading does not dedupe at all

I wrote "appendUnderHeading dedupes only against an identical line." That is not what it does. appendUnderHeading (core/tools/aidlc-lib.ts:5374) resolves the heading, finds the next ## boundary, and splices the text in. There is no comparison anywhere in it.

The dedupe is one level up, in aidlc-learnings.ts:476 — content.includes(marker), where marker is cidMarker(stageSlug, sel.candidate_id). So the key is the (stage, candidate_id) pair, not the rule text. That makes the append-only problem you raised slightly worse than I described: a second language rule from a different candidate id appends even when it is byte-identical to the first, let alone when it contradicts it.

The conclusion is unchanged — both rules can sit on disk, so the tie-break clause is still needed — but the mechanism I cited for it was wrong. The comment in t263 that repeated the same error is corrected in the same commit.

2. A deterministic single-current-language record does not need a State Version bump

I said your second option "lives" at State Version 7 → 8. That was wrong, and it made your alternative sound unavailable when it is not.

replaceSection already exists (core/tools/aidlc-lib.ts:5399) and the practices-discovery affirmation already uses it exactly this way — aidlc-state.ts:2873 overwrites the five ## … sections of team.md on a re-run instead of accumulating duplicates. So a replace-on-write, single-current-language record is implementable with existing infrastructure, no state-format change involved.

That said, it is not what this PR needs. You offered two routes — make the brief authoritative for delegated work with persisted memory as a fallback, or introduce a deterministic single-current-language record — and this PR implements the first, together with the regression case you asked for (an existing persisted language, then an explicit switch, then a delegated stage). The tie-break is what makes the fallback unambiguous in the case where the brief has not already decided the language.

Choosing that route was deliberate on the merits, not a fallback from the other one: scoping a replace-on-write to a single rule family would make the memory write path conditional on the content of the rule being written, and every other learning in the system appends. That is a change to the write path rather than to the rule layer, so it does not belong in this PR in either case.

The State Version 7 → 8 point does still apply, but only to the stronger claim — making the resolved language a machine-checkable field the engine enforces, rather than prose the model is asked to follow. That is the limitation I flagged, and it stands.

What the re-check changed in the tests

Auditing my own claims also meant mutating the suite to see whether it would actually catch a regression. Four places where it would not:

• A contradicting fifth rule passed. Appending "ALWAYS write every artifact in English; the rules above are advisory only" to ## Mandated left all 12 tests green while inverting the feature. The rule-layer tests proved the four rules were present, never that nothing countermanded them. t263 now pins the closed set: exactly four language rules under ## Mandated, each a known label, and no entry in the section carrying a countermanding phrase.
• The tie-break was only asserted as prose. The delivery test wrote a single rule, so the ambiguous two-rule case the clause exists for was never exercised — precisely your scenario. It now writes both and pins the ordering the tie-break depends on, so a bundle that sorted or deduped its memory lines would fail rather than silently leave the delegate unable to apply the rule.
• The precedence assertion was a tautology. indexOf(brief) < indexOf("AUTHORITATIVE") held no matter what the rule said, because the hook appends the bundle after the prompt. Replaced with a position-independence check: the brief line moves to the end of the prompt and the same four guarantees must still arrive.
• c2 accepted any resource string containing memory. file://docs/memory-notes.md passed, and for the non-Kiro harnesses it proved nothing beyond existsSync. Now: byte parity with core/hooks/aidlc-dispatch-rules.ts so (c)'s proof carries to every harness, an exact match on the memory glob, and the glob resolved to the org.md that actually ships the rules.

Each mutation was confirmed to turn the suite red and the suite green again on restore. t263 is now 13 tests / 444 assertions (was 12 / 189).

Current state

• bun run check — exit 0: package --check clean on all five harnesses, tsc --noEmit across three tsconfigs, biome check --error-on-warnings over 558 files
• Focused suite (t145-packaging-parity, t-memory-seed, t150-codex-packaging, t237-linter-sensor-version-pin, t240-opencode-packaging, t248-steering-content-delivery, t263, t68-version-changelog-sync) — 96 pass / 0 fail / 1093 assertions
• bun tests/run-tests.ts --ci --no-llm — 292 files, 6002 assertions, 1 failed file / 2 failed assertions: t248-codekb-scope-diff, where --mint returns the empty-tree hash 4b825dc6… and status therefore reports STALE instead of CURRENT. Pre-existing and unrelated — a clean git worktree on upstream/v2 at c73ee984 fails the same two assertions. (My earlier report of three pre-existing reds was measured on Windows; on this machine those three pass. This is the measured set.)
• Rebased on c73ee984, 0 commits behind upstream/v2. Still 2.5.38, which is unreleased upstream — will re-bump if something merges first.

[apackeer]

Verified the new work through 809e631. The original ordering issue is fixed: the live Conversation language: brief now outranks stale persisted memory, and the direct-edit ambiguity has been tightened. Two blockers remain before this is ready for another approval pass:

1. The new write-path rule is too broad. core/memory/org.md:95 says the §13 learnings ritual is the “ONLY sanctioned write path” into the entire active-space memory tree. That conflicts with Practices Discovery, whose required Step 7 runs aidlc-state.ts practices-promote and writes project.md and team.md (core/aidlc-common/stages/inception/practices-discovery.md:193-215; implementation at core/tools/aidlc-state.ts:2711-2724,2940-2953). Please scope the prohibition to persisting conversation-language switches, or to direct agent edits, so it does not countermand the existing deterministic promotion writer.

2. The branch needs another rebase/re-bump. It is four commits behind current v2; GitHub reports mergeStateStatus: DIRTY. Upstream is now 2.5.41, while this branch still claims 2.5.38, and upstream has taken the t263 test number. The merge conflicts cover CHANGELOG/README/version projections and the coverage registry. Please rebase, bump to the next available patch, rename the test, regenerate dist/, and rerun the relevant checks.

Two test limitations are also worth tightening during that pass:

• The switch regression manually writes both persisted rules and injects Conversation language: English into the prompt (t263-conversation-language-rule.test.ts:541-568). It proves bundle delivery/order, but not that the conductor observes an explicit switch and regenerates the brief line.
• The c2 harness test checks Kiro IDE’s CLI-only agent JSON and dispatch hook, while the IDE’s actual delivery surface is .kiro/steering/aidlc-active-memory.md (harness/kiro-ide/manifest.ts:107-110). Existing tests cover that steering generally, but this new language-rule delivery assertion does not.

Local verification on the current PR head:

• focused t263-conversation-language-rule: 13 pass / 0 fail, 444 expectations
• bun run check: package parity clean on all five harnesses; all three TypeScript configs pass; Biome passes across 558 files
• GitHub currently has no attached checks

So the precedence fix is substantively in the right direction, but I am keeping this blocked on the overbroad memory-write rule and the required rebase/version conflict resolution.

[masamaru0513]

Thank you for the review on 809e631. Both blockers and the two test limitations are addressed.

1. Write-path rule scope. Scoped to both routes you offered. The clause now reads the ONLY sanctioned write path for persisting a conversation-language switch into aidlc/spaces/<active-space>/memory/, and closes with it does not govern the deterministic memory writers a stage invokes by contract, such as aidlc-state.ts practices-promote, which own the stamped ## Mandated / ## Forbidden rules and the five replaced team.md sections rather than the ## Corrections language record. The promotion write path itself is covered deterministically by t75 (6 pass: the five team.md section replacements, the dated project.md appends, and PRACTICES_AFFIRMED).

2. Rebase and version. Rebased onto 035371ab, 0 commits behind. Bumped to 2.5.43, renamed the test to t266, and regenerated all ten dist/ projections. Conflicts resolved in CHANGELOG, README, aidlc-version.ts ×6, and gen-coverage-registry.

3. The switch regression injecting the brief line. Your point stands — that the conductor observes an explicit switch and regenerates the line is still unproven, and the new e2 closes only the rule-side failure paths: the obligation sits on the orchestrator rather than the delegate, it applies to every subsequent brief, and the switch is immediate with no persisted rule outranking the brief or a later explicit switch request. Delivery of that obligation to the conductor's own context is c3 below. Closing it deterministically would mean the engine producing the line rather than the model — a dispatch-path change rather than a rule-layer one — so I have left it outside this PR.

4. c2 inspecting Kiro IDE's CLI-only surface. Correct. The new c3 walks memoryInclude and asserts each harness's own syntax: Kiro IDE's .kiro/steering/aidlc-active-memory.md #[[file:…/org.md]] reference plus inclusion: always, Claude's @-import, the Codex AIDLC_RULES_DIR, the Kiro CLI conductor's resource glob, and opencode's instructions. The switch is exhaustive, so a new harness cannot ship an unproven include.

Verification

• bun run check — exit 0: package --check clean on all five harnesses, tsc --noEmit across three configs, Biome over 571 files
• t266-conversation-language-rule — 16 tests / 504 assertions (13 / 444 at your review). Each new assertion was confirmed red by breaking the contract it pins
• Focused suite (t145-packaging-parity, t-memory-seed, t150, t237, t240, t248-steering-content-delivery, t266, t68, gen-coverage-registry) — 133 pass / 0 fail
• bun tests/run-tests.ts --ci --no-llm — 299 files, 2 failed files / 3 failed assertions (t248-codekb-scope-diff, t163-reaper-steal-race). A worktree on clean upstream/v2 fails 3 files / 5 assertions, so this set is a subset

[masamaru0513]

Correction to the version above: #689 took 2.5.43 while I was pushing, so this is rebased onto a795583a and re-bumped to 2.5.44 (CHANGELOG, README badge, and the six aidlc-version.ts projections updated; dist/ regenerated). bun run check is exit 0 and the focused suite is unchanged at 133 pass / 0 fail. GitHub now reports the branch mergeable.

[apackeer]

Thanks for the latest update. The two prior blockers are addressed: the write-path rule is now scoped so it no longer countermanded practices-promote, and the branch is rebased, re-bumped, regenerated, and mergeable. I also reran the focused suite (133 pass / 0 fail) and bun run check; both pass.

This is close. I see one remaining policy ambiguity to resolve, with two manifestations:

1. core/memory/org.md:95 says the established language holds for the whole workflow, but an explicitly switched language that the human declines to persist is carried only for the rest of the session. A workflow can be parked and resumed in a later session, and core/hooks/aidlc-session-start.ts:251-259 injects no language. A bare /aidlc --resume therefore has no language signal and can fall back to stale memory or the initial description without another explicit switch. Please either scope the guarantee to the current conversation/session and define fresh-session fallback, or provide a durable current-language mechanism. I recommend the narrower session-scoped rule for this PR.

2. The persisted fallback groups project.md and team.md together, but its LAST-one-wins tie-break only defines duplicates within “that file” (core/memory/org.md:94). The learnings ritual permits project or team scope (stage-protocol.md:1099,1152-1154), while runtime always concatenates team before project (core/tools/aidlc-graph.ts:472). A newer team-level language rule can therefore conflict with a stale project-level rule without a defined winner. Please make language-switch persistence project-only with project explicitly outranking a team default, or define another unambiguous cross-file precedence. Add a split-team/project regression; the current test writes both rules into project.md (t266:641-652).

Small test follow-up while touching t266: add Initial description: and Workflow-selected scope: to REQUIRED_TOKENS; the claim-sources sensor matches both prefixes literally.

I am not asking to expand this into deterministic language enforcement, tool-generated audit localization, or a broader architecture change. Once the session boundary and persisted fallback are made internally consistent and those focused assertions are added, I have no other blocker from this pass.

[masamaru0513]

Thank you for reading this so carefully, and sorry for the extra rounds.

Both points came down to the same thing you spotted — I had written promises the engine doesn't keep. Fixed in b0f0cb77, taking the narrower option each time.

The guarantee is session-scoped now, and I made the fresh-session path explicit rather than leaving it to inference: re-resolve before the first dispatch, from the persisted rule, else the artifacts already written, else the initial description — and if all of them are silent, ask instead of assuming English. I also spelled out that re-resolving isn't a switch, so it can't drift into the §13 write path.

Persistence is project-only, and project.md outranks a team.md default because the rule says so rather than because of where it lands in the bundle. Naming org → team → project → phase in the rule text felt worth the words — it's the reason a positional reading gets this backwards.

e3 is the split case: default in team.md, switch in project.md, dispatched with no brief line. It pins that team really does arrive first, which is what makes the stated precedence load-bearing rather than decorative. t266 is 19 / 564, and I broke each new assertion to confirm it goes red — including reverting e3 to the single-file shape, which it catches. REQUIRED_TOKENS has the two prefixes.

bun run check clean, focused suite 136 / 0, --ci --no-llm still the same two pre-existing failures. Description updated too.

[apackeer]

Verified through b0f0cb77. The remaining review points are resolved: the guarantee is now explicitly session-scoped with a total fresh-session fallback; language-switch persistence is project-only with stated project-over-team precedence; the split team.md/project.md case is covered; and the two exact source-register prefixes are pinned.

Local verification:

• focused package/memory/steering/version/language suite: 136 pass / 0 fail
• bun run check: exit 0 (all five package projections, three TypeScript configs, and Biome)

No blocking findings. The documented model-directed limitation remains appropriately scoped.

[masamaru0513]

@apackeer @leandrodamascena
Thank you both for the detailed reviews and the approvals! 🙏

I see the CI workflow is currently waiting for a maintainer's approval to run.
Please let me know if there's anything else needed on my end, otherwise I will wait for the results!