<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-05-19-1-retrospective-default-policy-architecture/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-19-1-retrospective-default-policy-architecture/</id>
  <title>Retrospective Default-on Policy Architecture</title>
  <updated>2026-05-19T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-05-19-1-retrospective-default-policy-architecture/"/>
  <summary>Retrospective generation becomes a deterministic pure-Python module on by default at mission boundaries, because agent invocation is too slow and irreproducible.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Through 3.1.x, retrospective learning in Spec Kitty was effectively gated by two environment variables (&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RETROSPECTIVE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_MODE&lt;/code&gt;), and the runtime wired &lt;code dir=&quot;auto&quot;&gt;facilitator_callback=None&lt;/code&gt; so even an “enabled” strict path failed closed instead of producing useful learning. The user-facing &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent retrospect synthesize&lt;/code&gt; command — a proposal preview/apply tool — became the &lt;em&gt;de facto&lt;/em&gt; authoring surface because it had a silent fallback that fabricated empty completed records when artifacts looked sufficient. As a result, completed missions rarely produced useful retrospective records, and post-merge documentation (PR #1136) overstated what &lt;code dir=&quot;auto&quot;&gt;summary&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;synthesize&lt;/code&gt; actually capture.&lt;/p&gt;
&lt;p&gt;The product thesis from the 3.2.0 epic: retrospective learning should be a core feedback loop, not an env-gated experimental terminus trap. Specifically:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Every completed mission should produce a useful &lt;code dir=&quot;auto&quot;&gt;retrospective.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Policy lives in durable, project-level configuration (&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; and charter frontmatter), not in environment variables.&lt;/li&gt;
&lt;li&gt;The default behavior is post-completion best-effort with warn-on-failure; strict governed projects can opt into pre-completion blocking gates.&lt;/li&gt;
&lt;li&gt;Authoring and proposal-application are distinct surfaces with distinct semantics.&lt;/li&gt;
&lt;li&gt;Doctrine/DRG/glossary changes never auto-apply by default.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This mission decides the architecture for that overhaul. Two architectural questions had to be answered before tasks could land:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Generator shape&lt;/strong&gt;: should the runtime invoke an agent profile (&lt;code dir=&quot;auto&quot;&gt;retrospective-facilitator.agent.yaml&lt;/code&gt;) for richer mediated analysis, or call a pure-Python module directly?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Policy precedence&lt;/strong&gt;: when both &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; and charter frontmatter define &lt;code dir=&quot;auto&quot;&gt;retrospective:&lt;/code&gt; settings, which wins?&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A third operational question — how to respond to the pytest collection blocker tracked in &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1137&quot;&gt;#1137&lt;/a&gt; — was decided in the same planning session and is recorded here for completeness.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Default-on is non-negotiable&lt;/strong&gt;: every completed mission must attempt generation. Latency budget therefore matters more than richness.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Determinism and testability&lt;/strong&gt;: the generator must be unit-testable without an agent harness and must produce the same output for the same inputs (load-bearing for FR-021’s “existing reductions remain byte-identical” guarantee).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Governance scope (DIRECTIVE_031, DIRECTIVE_032)&lt;/strong&gt;: retrospective authoring is a distinct bounded context from doctrine/DRG/glossary mutation; the boundary must be explicit and crossing it requires an anti-corruption layer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Charter authority (DIRECTIVE_001)&lt;/strong&gt;: governed projects expect charter to be authoritative for policy; config-file precedence cannot leak in by default.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;FR-024 frozen public surface for &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt;&lt;/strong&gt;: any “fix” for #1137 that imports from &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.models.*&lt;/code&gt; (instead of the top-level re-exports) would violate the architectural contract; the issue’s closing comment makes this explicit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No SaaS dependency&lt;/strong&gt;: this mission is local CLI/runtime work. Generator must run without hosted services and without &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC=1&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No structural auto-apply&lt;/strong&gt;: doctrine/DRG/glossary mutation always requires explicit human approval (carried in &lt;code dir=&quot;auto&quot;&gt;C-005&lt;/code&gt; of the spec).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;h3 id=&quot;for-generator-shape&quot;&gt;For generator shape&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A&lt;/strong&gt;: Pure-Python module — deterministic function in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/generator.py&lt;/code&gt; that reads mission artifacts and returns a &lt;code dir=&quot;auto&quot;&gt;RetrospectiveRecord&lt;/code&gt;. Runtime calls it directly.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B&lt;/strong&gt;: Profile invocation — runtime invokes the &lt;code dir=&quot;auto&quot;&gt;retrospective-facilitator.agent.yaml&lt;/code&gt; profile via the existing profile-invocation pipeline; output is an agent-authored record.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C&lt;/strong&gt;: Hybrid — pure-Python is the runtime default; policy can opt into profile invocation via &lt;code dir=&quot;auto&quot;&gt;retrospective.generator: profile&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;for-policy-precedence&quot;&gt;For policy precedence&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option P-A&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; wins by default; charter must explicitly opt in to authority.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option P-B&lt;/strong&gt;: Charter wins by default; charter may delegate to config via an explicit &lt;code dir=&quot;auto&quot;&gt;retrospective.precedence: config&lt;/code&gt; directive.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option P-C&lt;/strong&gt;: Both contribute additively; conflicting fields produce a resolution error.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;for-1137-resolution&quot;&gt;For #1137 resolution&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option E-A&lt;/strong&gt;: Upstream fix in &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; 5.1.1 — restore &lt;code dir=&quot;auto&quot;&gt;normalize_event_id&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;Event&lt;/code&gt; to top-level exports.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option E-B&lt;/strong&gt;: Local import fallback in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/validate.py&lt;/code&gt; to use a stable subpath (&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.models&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option E-C&lt;/strong&gt;: Pin &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; to a known-good version.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option E-D&lt;/strong&gt;: Documentation-only — diagnose as local env corruption (PEP 420 namespace package state), add CONTRIBUTING note, no code change.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;h3 id=&quot;generator-shape--option-a-pure-python-module&quot;&gt;Generator shape — Option A (Pure-Python module)&lt;/h3&gt;
&lt;p&gt;Decision Moment: &lt;code dir=&quot;auto&quot;&gt;01KS051316C8Z0SDEKZ2B088CS&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Chosen because:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Default-on at every mission boundary requires sub-second latency. Profile invocation routinely takes 5–30s (agent dispatch, network round-trip, completion).&lt;/li&gt;
&lt;li&gt;Determinism is a hard requirement for FR-021 (byte-identical historical reductions). A pure-Python function is byte-deterministic given the same inputs; an agent-invoked generator is not.&lt;/li&gt;
&lt;li&gt;Testability: unit tests scaffold mission artifacts on disk and call the generator directly; no agent harness mocks needed.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;retrospective-facilitator&lt;/code&gt; profile remains useful as a &lt;em&gt;human-mediated&lt;/em&gt; tool for richer post-mortems via the existing &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action retrospect&lt;/code&gt; style invocations. It is simply not the runtime default.&lt;/li&gt;
&lt;li&gt;Forward compatibility: the policy schema lands with a &lt;code dir=&quot;auto&quot;&gt;generator&lt;/code&gt; field that today accepts only &lt;code dir=&quot;auto&quot;&gt;&quot;python&quot;&lt;/code&gt;. Adding &lt;code dir=&quot;auto&quot;&gt;&quot;profile&quot;&lt;/code&gt; later requires no schema break — Option C is preserved as a future opt-in without committing to it now.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;policy-precedence--option-p-b-charter-wins-config-may-delegate&quot;&gt;Policy precedence — Option P-B (Charter wins; config may delegate)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Chosen because:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;DIRECTIVE_001 (“Architectural Integrity Standard”) and the project’s charter-first governance model require charter to be the authoritative governance surface. Letting config silently override would violate that expectation.&lt;/li&gt;
&lt;li&gt;The escape hatch (&lt;code dir=&quot;auto&quot;&gt;retrospective.precedence: config&lt;/code&gt; in charter frontmatter) covers the rare case where a charter explicitly wants config-level flexibility, without requiring boilerplate in every charter.&lt;/li&gt;
&lt;li&gt;The resolver returns &lt;code dir=&quot;auto&quot;&gt;(policy, source_map)&lt;/code&gt; where &lt;code dir=&quot;auto&quot;&gt;source_map&lt;/code&gt; records the origin of every leaf field; observers can therefore always tell which file/key drove a given decision.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;1137--option-e-d-documentation-only&quot;&gt;#1137 — Option E-D (Documentation only)&lt;/h3&gt;
&lt;p&gt;Decision Moment: &lt;code dir=&quot;auto&quot;&gt;01KS0513SEHSEE82WN4RJBFDRG&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Chosen because:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The issue is closed as not-a-bug. The 5.1.0 wheel is fine; the symptom is local PEP 420 namespace-package corruption from a partial &lt;code dir=&quot;auto&quot;&gt;pip uninstall&lt;/code&gt;. CI is unaffected (per the closing comment, &lt;code dir=&quot;auto&quot;&gt;tests/agent/test_orchestrator_commands_integration.py::TestAcceptMission&lt;/code&gt; collects cleanly in fresh CI venvs).&lt;/li&gt;
&lt;li&gt;Option E-B (local fallback) was explicitly rejected by the issue’s closing comment: importing from &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.models.*&lt;/code&gt; instead of the top-level surface would either violate the FR-024 frozen public-surface contract (enforced by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_tracker_public_imports.py&lt;/code&gt;) or require expanding that contract. Both options trade architectural integrity for a workaround to a local-env problem.&lt;/li&gt;
&lt;li&gt;Option E-A (upstream fix) is on the critical path of the 3.2.0 release and requires a separate package release; not justified for a not-a-bug.&lt;/li&gt;
&lt;li&gt;Option E-C (version pin) defers contract drift and may regress other 5.1.x improvements.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Action&lt;/strong&gt;: add a diagnostic note to &lt;code dir=&quot;auto&quot;&gt;CONTRIBUTING.md&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;python -c &quot;import spec_kitty_events; print(spec_kitty_events.__file__, spec_kitty_events.__path__)&quot;&lt;/code&gt; check, the &lt;code dir=&quot;auto&quot;&gt;_NamespacePath(...)&lt;/code&gt; symptom, and the &lt;code dir=&quot;auto&quot;&gt;uv sync --reinstall-package spec-kitty-events&lt;/code&gt; fix command).&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The default-on retrospective path adds &amp;#x3C; 2s wall-clock to mission completion (NFR-005) — meets the budget for routine use.&lt;/li&gt;
&lt;li&gt;Unit tests do not require agent dispatch infrastructure; the entire retrospective surface can be exercised without a live LLM or external service.&lt;/li&gt;
&lt;li&gt;Charter remains the authoritative governance surface for governed projects. Operators reading the resolved policy can always point to a specific charter or config key as its source.&lt;/li&gt;
&lt;li&gt;The frozen &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; public surface (FR-024 from the consumer-contract dossier) remains intact. Future contributors who hit the #1137 namespace-package symptom locally get a clear diagnostic in CONTRIBUTING.md instead of a hidden code path that masks the corruption.&lt;/li&gt;
&lt;li&gt;Forward compatibility for profile-invocation generators is preserved without committing to the implementation cost now.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The default generator produces a less “thoughtful” record than a profile-mediated one might. Mitigated by SC-004 (the generator is validated against three real completed missions in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; during the mission-review report) and by keeping the profile-invocation path available as an explicit operator action.&lt;/li&gt;
&lt;li&gt;Governed projects must understand that charter wins by default. This is a learning cost for operators coming from systems where config-files-override is conventional. Mitigated by the documented &lt;code dir=&quot;auto&quot;&gt;retrospective.precedence: config&lt;/code&gt; escape hatch and by the resolver’s &lt;code dir=&quot;auto&quot;&gt;source_map&lt;/code&gt; always being inspectable.&lt;/li&gt;
&lt;li&gt;The CONTRIBUTING note for #1137 places the fix in a contributor-facing doc rather than a code path. Contributors who never read CONTRIBUTING and hit the symptom waste cycles. Mitigated by the fix command (&lt;code dir=&quot;auto&quot;&gt;uv sync --reinstall-package spec-kitty-events&lt;/code&gt;) being short and the error signature being googleable.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;retrospective-facilitator.agent.yaml&lt;/code&gt; profile is retained but reframed as descriptive metadata for human-mediated retrospectives rather than the runtime’s authoring path. No deletion.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;agent retrospect synthesize&lt;/code&gt; command keeps its existing signature; only the default-path behavior (when no record exists) tightens — the legacy fabrication path is preserved behind an explicit &lt;code dir=&quot;auto&quot;&gt;--fabricate-empty&lt;/code&gt; flag.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We will know this decision was correct if, post-merge:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;uv run pytest tests/retrospective/ -q&lt;/code&gt; exits 0 and the generator unit tests reach ≥ 90% coverage (NFR-004, matching charter).&lt;/li&gt;
&lt;li&gt;A representative mission completion under default policy adds ≤ 2s wall-clock (NFR-005), verified by a focused integration test.&lt;/li&gt;
&lt;li&gt;The shipped &lt;code dir=&quot;auto&quot;&gt;spec-kitty retrospect create --mission &amp;#x3C;handle&gt;&lt;/code&gt; command produces real, schema-valid records for at least three already-completed missions in this repo (&lt;code dir=&quot;auto&quot;&gt;068-post-merge-reliability-and-release-hardening&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;034-feature-status-state-model-remediation&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;047-namespace-aware-artifact-body-sync&lt;/code&gt; per SC-004).&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;policy_source&lt;/code&gt; map on emitted retrospective events lets operators trace every blocking or warning event back to a specific &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; or charter frontmatter key.&lt;/li&gt;
&lt;li&gt;The FR-024 architectural test (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_tracker_public_imports.py&lt;/code&gt;) remains green, confirming no code path imports &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.models.*&lt;/code&gt; directly.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Confidence: &lt;strong&gt;high&lt;/strong&gt; for the generator and #1137 decisions (the latter is constrained by an existing immutable architectural contract). &lt;strong&gt;Medium-high&lt;/strong&gt; for the policy-precedence decision — if operator feedback during the 3.2.0 stabilization window reveals charter-wins-by-default is confusing for adopters, a future ADR may flip the default after gathering data; the &lt;code dir=&quot;auto&quot;&gt;retrospective.precedence&lt;/code&gt; field is the forward-compat surface for that.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a-pure-python-generator--chosen&quot;&gt;Option A (Pure-Python generator) — chosen&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Deterministic, byte-stable output for FR-021 reduction guarantee&lt;/li&gt;
&lt;li&gt;✅ Sub-second latency budget&lt;/li&gt;
&lt;li&gt;✅ Unit-testable without agent harness&lt;/li&gt;
&lt;li&gt;✅ Forward-compat: schema accepts &lt;code dir=&quot;auto&quot;&gt;generator: python&lt;/code&gt; today, &lt;code dir=&quot;auto&quot;&gt;generator: profile&lt;/code&gt; later&lt;/li&gt;
&lt;li&gt;❌ Less “thoughtful” than a profile-mediated record could be (mitigated by SC-004 quality gate)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-profile-invocation&quot;&gt;Option B (Profile invocation)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Aligns with the agent-mediated learning doctrine direction&lt;/li&gt;
&lt;li&gt;✅ Richer post-mortem signal per mission&lt;/li&gt;
&lt;li&gt;❌ 5–30s latency per mission completion — incompatible with default-on&lt;/li&gt;
&lt;li&gt;❌ Couples retrospective generation to whichever coding agent is configured&lt;/li&gt;
&lt;li&gt;❌ Testing requires agent harness mocks&lt;/li&gt;
&lt;li&gt;❌ Non-deterministic output complicates FR-021&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-c-hybrid&quot;&gt;Option C (Hybrid)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Best of both worlds in principle&lt;/li&gt;
&lt;li&gt;❌ Doubles the test surface for the runtime default&lt;/li&gt;
&lt;li&gt;❌ Requires shipping the profile-invocation path in this mission even if no project uses it&lt;/li&gt;
&lt;li&gt;💡 &lt;em&gt;Preserved as a future opt-in via the &lt;code dir=&quot;auto&quot;&gt;generator&lt;/code&gt; field’s enum.&lt;/em&gt; If operator demand materializes during 3.2.x, a follow-up ADR can extend the resolver and runtime without a schema break.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-p-a-config-wins-by-default&quot;&gt;Option P-A (Config wins by default)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Matches conventional config-file precedence&lt;/li&gt;
&lt;li&gt;❌ Violates charter-first governance for governed projects without explicit opt-in&lt;/li&gt;
&lt;li&gt;❌ Charter would need boilerplate to assert authority on every governed project&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-p-b-charter-wins-by-default-config-may-delegate--chosen&quot;&gt;Option P-B (Charter wins by default; config may delegate) — chosen&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Charter-first governance preserved&lt;/li&gt;
&lt;li&gt;✅ Single, documented escape hatch (&lt;code dir=&quot;auto&quot;&gt;retrospective.precedence: config&lt;/code&gt;) for projects that want config-flexibility&lt;/li&gt;
&lt;li&gt;✅ &lt;code dir=&quot;auto&quot;&gt;source_map&lt;/code&gt; makes resolution decisions inspectable&lt;/li&gt;
&lt;li&gt;❌ Learning curve for operators who expect config-wins&lt;/li&gt;
&lt;li&gt;💡 If feedback during 3.2.x stabilization shows this is consistently confusing, the decision is reversible via a follow-up ADR — &lt;code dir=&quot;auto&quot;&gt;retrospective.precedence&lt;/code&gt; is the forward-compat lever.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-p-c-additive&quot;&gt;Option P-C (Additive)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;❌ Conflicting fields would raise resolution errors, blocking healthy projects&lt;/li&gt;
&lt;li&gt;❌ Operators would need to keep both files in sync field-by-field&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-e-a-upstream-fix-1137&quot;&gt;Option E-A (Upstream fix #1137)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Cleanest long-term&lt;/li&gt;
&lt;li&gt;❌ Separate package release on the 3.2.0 critical path&lt;/li&gt;
&lt;li&gt;❌ Not justified for a not-a-bug&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-e-b-local-fallback-for-1137&quot;&gt;Option E-B (Local fallback for #1137)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;❌ Violates the FR-024 frozen public-surface contract&lt;/li&gt;
&lt;li&gt;❌ Masks local-env corruption that future contributors should still hit visibly&lt;/li&gt;
&lt;li&gt;❌ The issue’s closing comment explicitly rules this out&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-e-c-version-pin&quot;&gt;Option E-C (Version pin)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;❌ Defers contract drift; may regress 5.1.x improvements&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-e-d-documentation-only--chosen&quot;&gt;Option E-D (Documentation only) — chosen&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;✅ Respects the issue’s closing decision (not-a-bug)&lt;/li&gt;
&lt;li&gt;✅ Preserves the frozen public surface&lt;/li&gt;
&lt;li&gt;✅ Zero blast radius — single doc edit&lt;/li&gt;
&lt;li&gt;❌ Contributors who skip CONTRIBUTING and hit the symptom waste cycles (mitigated by short fix command)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;bounded-context-map-per-directive_031&quot;&gt;Bounded-Context Map (per DIRECTIVE_031)&lt;/h2&gt;
&lt;p&gt;This mission spans four bounded contexts. The crossings are explicit and mediated:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;┌──────────────────────────────┐         ┌──────────────────────────────┐&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ Retrospective Authoring      │         │ Mission Lifecycle /          │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                              │         │ Event Log                    │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - RetrospectivePolicy        │         │                              │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - RetrospectiveRecord        │         │ - runtime_bridge.py          │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - generator (pure Python)    ├────────►│ - retrospective_terminus.py  │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - writer (merge/overwrite)   │ emits   │ - status.events.jsonl        │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - events (additive)          │ events  │ - reducer (no-op for         │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                              │         │   retrospective events)      │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└────────┬─────────────────────┘         └──────────────────────────────┘&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;         &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;         &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ proposals[] (data only)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;         &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;▼&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;┌──────────────────────────────┐         ┌──────────────────────────────┐&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ agent retrospect synthesize  │         │ Doctrine / DRG / Glossary    │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ (anti-corruption layer)      ├────────►│                              │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                              │ apply   │ - human-approved mutations   │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - preview proposals          │ (gated) │ - structural changes always  │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ - apply with human approval  │         │   require explicit consent   │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└──────────────────────────────┘         └──────────────────────────────┘&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Retrospective Authoring → Event Log&lt;/strong&gt;: explicit, additive event payloads (&lt;code dir=&quot;auto&quot;&gt;RetrospectiveCaptured&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;RetrospectiveCaptureFailed&lt;/code&gt;). Reducer treats them as no-ops for lane state.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Retrospective Authoring → Doctrine/DRG/Glossary&lt;/strong&gt;: never direct. Proposals are data; application goes through the &lt;code dir=&quot;auto&quot;&gt;synthesize&lt;/code&gt; anti-corruption layer with human approval.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLI Surface → Retrospective Authoring&lt;/strong&gt;: through documented JSON contracts in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/contracts/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Implementation plan: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/plan.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Decision rationale: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/research.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Data model: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/data-model.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Contracts: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/contracts/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Decision Moment artifacts: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/retrospective-default-policy-01KS049J/decisions/DM-01KS051316C8Z0SDEKZ2B088CS.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DM-01KS0513SEHSEE82WN4RJBFDRG.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Related ADR: &lt;a href=&quot;/adr/3.x/2026-04-27-1-retrospective-gate-shared-module/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-27-1-retrospective-gate-shared-module.md&lt;/code&gt;&lt;/a&gt; — prior retrospective gate architecture this mission builds on&lt;/li&gt;
&lt;li&gt;Related ADR: &lt;a href=&quot;/adr/3.x/2026-04-25-1-shared-package-boundary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/a&gt; — establishes the frozen &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; public surface that constrains the #1137 decision&lt;/li&gt;
&lt;li&gt;DIRECTIVES applied: &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_001&lt;/code&gt; (Architectural Integrity), &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_003&lt;/code&gt; (Decision Documentation), &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_031&lt;/code&gt; (Context-Aware Design), &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_032&lt;/code&gt; (Conceptual Alignment)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
