<?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-24-1-charter-freshness-ux-contract/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-24-1-charter-freshness-ux-contract/</id>
  <title>ADR: Charter Freshness UX Contract</title>
  <updated>2026-05-24T00: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-24-1-charter-freshness-ux-contract/"/>
  <summary>Establishes one freshness vocabulary across the charter command family, anchored by a tri-state graph identity carried on every decay report the lint engine emits.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-16-1-doctrine-layer-merge-semantics.md&lt;/code&gt;&lt;/a&gt; (predecessor — locks the layer-merge semantics this contract reports on)&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-2-pack-augmentation-vocabulary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-2-pack-augmentation-vocabulary.md&lt;/code&gt;&lt;/a&gt; (sibling — &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; vocabulary used in the freshness banners)&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-3-shipped-to-built-in-cutover/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-3-shipped-to-built-in-cutover.md&lt;/code&gt;&lt;/a&gt; (sibling — the &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; label this contract surfaces)
&lt;strong&gt;Related issues&lt;/strong&gt;: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1099&quot;&gt;#1099&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1100&quot;&gt;#1100&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1101&quot;&gt;#1101&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1104&quot;&gt;#1104&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A developer adopting Spec Kitty today encounters fragmented freshness signals across the
charter command family. Concretely:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter status&lt;/code&gt; reports &lt;code dir=&quot;auto&quot;&gt;SYNCED / No decay detected&lt;/code&gt; even when the project
Doctrine Reference Graph (DRG) is missing, because the existing status path only
inspects file existence, not the relationship between charter source, synced bundle, and
synthesized DRG.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter lint&lt;/code&gt; returns an empty &lt;code dir=&quot;auto&quot;&gt;DecayReport&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;Scanned 0 nodes&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;No decay detected&lt;/code&gt;) when &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/graph.yaml&lt;/code&gt; is absent. This is the
fresh-checkout default and is indistinguishable from a healthy zero-finding scan
(&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1099&quot;&gt;#1099&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter synthesize&lt;/code&gt; does not publish a deterministic post-condition. There is
no marker that distinguishes “synthesize ran and produced nothing because the project
has no overrides” from “synthesize never ran” (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1104&quot;&gt;#1104&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;There is no session-start preflight that ties these signals together, so governed
commands silently degrade against stale or absent doctrine
(&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1100&quot;&gt;#1100&lt;/a&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The shared root cause is &lt;strong&gt;vocabulary&lt;/strong&gt;: every command reports its own slice of the
freshness story in its own shape, so the operator cannot compose the signals into a single
remediation decision. The four issues above are symptoms of a missing contract, not four
independent bugs.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;We establish a single freshness UX contract that spans the charter command family. The
contract has four parts. Wave 1 of this mission (WP01) lands part (1); waves 2–4 land
parts (2)–(4) under the same vocabulary.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Tri-state graph identity on &lt;code dir=&quot;auto&quot;&gt;DecayReport&lt;/code&gt; (WP01, this ADR’s anchor).&lt;/strong&gt; The lint engine
introduces a &lt;code dir=&quot;auto&quot;&gt;GraphState(StrEnum)&lt;/code&gt; enum with three values: &lt;code dir=&quot;auto&quot;&gt;merged&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;built_in_only&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;. Every &lt;code dir=&quot;auto&quot;&gt;DecayReport&lt;/code&gt; carries &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt;. The
&lt;code dir=&quot;auto&quot;&gt;LintEngine.run()&lt;/code&gt; orchestrator resolves the graph via a deterministic three-step
fallback — project DRG → built-in DRG → none — and labels the report accordingly.
The CLI human banner branches on &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt; per the contract table in
&lt;code dir=&quot;auto&quot;&gt;contracts/charter-lint-json.md&lt;/code&gt;. The &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; payload exposes &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt; at the
top level. This satisfies FR-001 .. FR-004.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Freshness sub-payload on &lt;code dir=&quot;auto&quot;&gt;charter status --json&lt;/code&gt; (WP02).&lt;/strong&gt; The status JSON gains a
&lt;code dir=&quot;auto&quot;&gt;freshness&lt;/code&gt; object with separate sub-states for &lt;code dir=&quot;auto&quot;&gt;charter_source&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;synced_bundle&lt;/code&gt;,
and &lt;code dir=&quot;auto&quot;&gt;synthesized_drg&lt;/code&gt;. Each sub-state carries &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;last_change&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;remediation&lt;/code&gt;. The state vocabulary matches the preflight surface (see (3)) so
the two commands compose. This satisfies FR-005.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter preflight&lt;/code&gt; surface (WP03).&lt;/strong&gt; A new command and a matching session-start hook
compute a &lt;code dir=&quot;auto&quot;&gt;CharterPreflightResult&lt;/code&gt; with explicit &lt;code dir=&quot;auto&quot;&gt;passed&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;checks&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;auto_refresh_applied&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;blocked_reason&lt;/code&gt; fields. It emits deterministic JSON and never
silently no-ops. When the preflight detects a fresh-checkout state, it either runs the
safe refresh sequence (&lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt;) or
blocks with one exact recovery command, governed by a documented configuration flag.
The preflight refuses to auto-refresh when uncommitted generated artifacts exist in the
worktree. This satisfies FR-006 .. FR-008.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Documented synthesize post-condition (WP04).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; guarantees that
either &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/graph.yaml&lt;/code&gt; exists and is valid, or a &lt;code dir=&quot;auto&quot;&gt;built_in_only: true&lt;/code&gt;
marker is recorded in &lt;code dir=&quot;auto&quot;&gt;synthesis-manifest.yaml&lt;/code&gt; and downstream commands honour it. The
synthesizer is responsible for the atomicity that prevents the
“manifest says built_in_only but graph.yaml exists” conflict state from arising; if it
is detected at read time, the freshness surface treats the manifest as authoritative
and reports &lt;code dir=&quot;auto&quot;&gt;state=&quot;invalid&quot;&lt;/code&gt; with a remediation hint. This satisfies FR-009.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The four parts share one piece of vocabulary: the &lt;code dir=&quot;auto&quot;&gt;state&lt;/code&gt; value space
(&lt;code dir=&quot;auto&quot;&gt;fresh&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;stale&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;invalid&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;skipped&lt;/code&gt;) and the &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt; value space
(&lt;code dir=&quot;auto&quot;&gt;merged&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;built_in_only&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;). Every public JSON surface and every human banner
uses those exact strings; there are no synonyms.&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;h3 id=&quot;a--eager-auto-refresh-on-every-cli-invocation&quot;&gt;A — Eager auto-refresh on every CLI invocation&lt;/h3&gt;
&lt;p&gt;Every governed command silently runs &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;synthesize&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt;
before doing anything else. This was rejected for two reasons:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;NFR-001 budget&lt;/strong&gt;. The mission’s freshness preflight budget is &amp;#x3C; 300 ms warm /
&amp;#x3C; 1.0 s cold. A full synthesize on every invocation costs seconds on a non-trivial
charter — well outside the budget and intolerable for interactive use.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Surprise factor&lt;/strong&gt;. Silent regeneration on every command would overwrite uncommitted
generated artifacts without operator consent. The preflight (FR-008) treats that case
as a hard block; promoting it to the default would invert the safety property.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;b--status-only-patch-fix-charter-status-and-ignore-the-rest&quot;&gt;B — Status-only patch (fix &lt;code dir=&quot;auto&quot;&gt;charter status&lt;/code&gt; and ignore the rest)&lt;/h3&gt;
&lt;p&gt;Tighten &lt;code dir=&quot;auto&quot;&gt;charter status&lt;/code&gt; to detect a missing project DRG and rely on operators to read it
before running other commands. This was rejected because three of the four symptoms
(#1099 empty lint, #1100 silent degradation in &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;dashboard&lt;/code&gt;, #1104
opaque synthesize post-condition) live downstream of status. A status-only patch leaves
those symptoms intact and re-introduces the original “fragmented signals” failure mode.&lt;/p&gt;
&lt;h3 id=&quot;c--inline-graph_state-in-existing-fields-drg_node_count--1-or-magic-string&quot;&gt;C — Inline &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt; in existing fields (&lt;code dir=&quot;auto&quot;&gt;drg_node_count: -1&lt;/code&gt; or magic string)&lt;/h3&gt;
&lt;p&gt;Smuggle the tri-state through existing fields rather than adding &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt;. Rejected
on contract-hygiene grounds: every external consumer (&lt;code dir=&quot;auto&quot;&gt;charter status --json&lt;/code&gt; callers,
the dashboard, governed agents) would have to learn the sentinel convention and decode it
the same way. An explicit enum is cheaper to document, cheaper to test, and impossible to
confuse with a legitimate node count.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Operators read one vocabulary across &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lint&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;synthesize&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;preflight&lt;/code&gt;.
The remediation hint is identical regardless of which command surfaced the gap.&lt;/li&gt;
&lt;li&gt;The dashboard, governed context, and agent-facing surfaces (&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;) can
rely on a single freshness model rather than re-inventing the check at each call site.&lt;/li&gt;
&lt;li&gt;Programmatic consumers get a stable JSON shape: &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt; is a top-level enum, not
a derived field; the freshness sub-payload is structurally identical on
&lt;code dir=&quot;auto&quot;&gt;charter status --json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter preflight --json&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--cost&quot;&gt;Negative / cost&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The lint engine signature changes: &lt;code dir=&quot;auto&quot;&gt;load_merged_drg(repo_root)&lt;/code&gt; now returns
&lt;code dir=&quot;auto&quot;&gt;tuple[Any | None, GraphState]&lt;/code&gt; rather than &lt;code dir=&quot;auto&quot;&gt;Any | None&lt;/code&gt;. Internal callers and tests
that patch &lt;code dir=&quot;auto&quot;&gt;load_merged_drg&lt;/code&gt; must update their stubs. The existing test fixtures in
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/charter_lint/test_engine.py&lt;/code&gt; are updated as part of WP01.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;DecayReport&lt;/code&gt; gains a required field. &lt;code dir=&quot;auto&quot;&gt;to_dict()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;to_json()&lt;/code&gt; emit the new field
unconditionally; the dataclass default is &lt;code dir=&quot;auto&quot;&gt;GraphState.MISSING&lt;/code&gt; so older callers that
construct &lt;code dir=&quot;auto&quot;&gt;DecayReport(...)&lt;/code&gt; without the field continue to work but report the missing
state explicitly.&lt;/li&gt;
&lt;li&gt;The CLI banner gains two new branches (&lt;code dir=&quot;auto&quot;&gt;built_in_only&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;). Integration tests
that asserted on the old “No decay detected / Scanned 0 nodes” string for fresh-checkout
repos must update. WP01 includes the matching test rewrites.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;migration-impact&quot;&gt;Migration impact&lt;/h3&gt;
&lt;p&gt;External consumers that grep &lt;code dir=&quot;auto&quot;&gt;charter lint --json&lt;/code&gt; for a particular finding shape are
unaffected: &lt;code dir=&quot;auto&quot;&gt;findings&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scanned_at&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;drg_node_count&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;drg_edge_count&lt;/code&gt; remain. New
consumers that want the tri-state read &lt;code dir=&quot;auto&quot;&gt;graph_state&lt;/code&gt;. No CHANGELOG breaking entry is
required for WP01 because the field is additive; the &lt;code dir=&quot;auto&quot;&gt;shipped → built-in&lt;/code&gt; rename in WP10
will carry its own CHANGELOG note.&lt;/p&gt;
&lt;h2 id=&quot;scope-of-this-adr&quot;&gt;Scope of this ADR&lt;/h2&gt;
&lt;p&gt;This ADR fixes the contract for the freshness UX across all four waves of the mission. It
does &lt;strong&gt;not&lt;/strong&gt; lock the schema for &lt;code dir=&quot;auto&quot;&gt;freshness.*&lt;/code&gt; sub-states beyond the value vocabulary —
that schema is finalised in WP02 and lives in the data model and JSON contract files. It
does &lt;strong&gt;not&lt;/strong&gt; mandate when &lt;code dir=&quot;auto&quot;&gt;charter preflight&lt;/code&gt; runs (every command vs session-start only);
that decision is recorded in WP03 against the matching research question (open question
3 in &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;This ADR is the foundation contract for WP01 .. WP04. Subsequent WPs in this mission build
on it; they do not amend it.&lt;/p&gt;</content>
</entry>
