ginee v0.26.0

Highlights

• Specialist cardinals can resume each other directly. Frontend ↔ QA iteration cycles (and other single-defect peer fixes) no longer relay through team-lead — 7 main-thread turns per cycle collapse to 2. Over 5–10 iterations on a single task, main-thread context savings approach the warm-reuse savings of #90 / D43. Round-trip cap default 3 per phase; escalation to team-lead on contradictory return, multi-cardinal surface, or scope change (#189).
• The wrapper-anchor pattern is now an official primitive. New core/protocols/adapter-wrapper-pattern.md names .claude/agents/<role>.md (and adapter siblings) as the canonical Tier-1 / Class-A entry of the compliance playbook (#135). Design invariant: hardenable properties (tools: · model: · description: · phase-participation:) live in frontmatter; charter prose MUST NOT restate the host-enforced rule. Per-adapter availability matrix (Claude / Cursor / Copilot / Codex / generic) ships with the protocol.
• Every dispatch now carries a scope-size estimate. Team-lead emits ≤15m / 15-60m / >60m + one-line signal before every cardinal dispatch — surfaces on dispatch-prompts, sub-issue bodies, and the iteration-protocol load decision. Previously trigger-circular ("loaded on >15m, with no step deciding") (#168).
• Phase-6 defects ship with a committed failing test. QA writes the reproducer; engineer's fix-oracle is "test passes locally". Permanent regression gate per defect class. Untestable defects (pure visual / human-in-loop / timing) flag testable: false + rationale (#184).
• Engineers self-verify before QA hand-off. Phase 4 acceptance raised from unit-only to a strict change-scoped fix-loop gate — every available suite (component / API / integration / E2E / pixel-check / script-quality / post-step health / deploy smoke per role) MUST run green before hand-off. QA Phase 5 reframed as backstop (independent re-execution) — MUST NOT first-pass discover (#177).
• SA realigned to classical-architect boundaries. phase-participation: [1, 2, 7] (excluded from 4/5/6); SA artefacts forbid implementation rendering (function/member identifiers · <file>:<line> citations · commit SHAs · handler-body snippets · wiring prescriptions). Two new Claude PreToolUse hooks (T14 / T15) enforce hard. Phase 7 governance review now conditional (#182).
• /ginee-iterate skill — review-cycle replies forward to the warm cardinal. Skill-runner no longer short-circuits the warm cardinal on small fixes — SendMessage relay preserves warm-reuse savings across 10–20 iteration cycles that previously bloated main-thread context by 50–100k tokens. Skill count 12 → 13 (#154).

Adopter migration

Existing installs run /ginee-update to apply. Update path is mechanically driven — install.{ps1,sh} --update-only nukes .agents/ginee/core/+adapters/+extras/, fetches the v0.26.0 ref, re-copies _shared/agents/*.md → .claude/agents/ (or adapter equivalent). The new SendMessage in specialist tools: arrays propagates automatically.

Notes

• No local/framework.config.yaml changes needed. Peer round-trip cap default is 3; override via iteration.peer-roundtrip-cap if needed. Estimation gate, defect-reproducer, self-verify all opt-out via existing compliance.disabled keys.
• Warm-reuse prerequisite remains — Claude adopters need CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json § env for SendMessage to be available; restart Claude Code after change. Adopters without warm-reuse fall back to team-lead-relay (no behaviour change).
• SA boundary enforcement is HARD — PreToolUse hooks (T14 / T15) block Task(subagent_type=solution-architect) in Phase 4/5/6 contexts and SA-owned-path edits carrying implementation rendering. Per-tactic opt-out: compliance.disabled: [pretooluse-task-hook] / [pretooluse-sa-artefact-hook].
• Full specs: migrations/ — estimation-gate-fires.md · defect-reproducer-contract.md · engineer-self-verify.md · sa-boundary-tightening.md · ginee-iterate-skill.md. The wrapper-anchor pattern doesn't ship a migration doc — the spec itself (core/protocols/adapter-wrapper-pattern.md) is the canonical reference.

ginee v0.25.0

Highlights

• Filed issues, sub-issues, and PR descriptions now read cold to a human. A new 5-item audience check on ginee-file-* skills enforces user-facing titles + 2-4 sentence Summary + framework-internal sections after the human summary. The opaque [6:qa-engineer] Overlap-invariants regression spec — permanent CI gate (#83 framework hygiene) voice no longer ships; contractors, new team members, and you-six-months-later can pick up tickets without loading framework jargon (#175).
• User-facing Phase-8 reports + delivery handoffs have a real schema. New core/templates/user-response.md — ## Result · ## What changed · ## Verification · ## Next · optional ## Notes ≤ 150 words + auto-mode addenda (## Delivery state · ## Accept / Feedback / Reject). No more 30-line walls-of-prose at the end of a task (#170).
• Dispatches to cardinals never ship as freeform paragraphs. Self-lint on core/protocols/dispatch-prompt-schema.md graduated from advisory to a binding pre-send gate — non-compliant payloads restructure inline before send. Tighter dispatches = lower per-task token cost.
• Non-compliant cardinal returns auto-fire carry-forward. Threshold-driven (≥ 2 missing required sections OR forbidden-pattern hit) → next dispatch to the same cardinal carries the rule forward automatically. Bounded second carve-out catches drifting cardinals (one format-only re-retry per task).
• CI regression guards extended for the Tier 2 + Tier 3 compliance hooks (#179) and the new adapter-binding rule in CLAUDE.md (#180) — every new framework rule now classifies enforcement per adapter at author time.

Adopter migration

No action required — purely additive. Existing dispatches on closed tasks unaffected (forward-only). The next ginee-authored issue / sub-issue / dispatch / Phase-8 response runs the new gates automatically.

Adopters writing custom issue templates under local/ SHOULD adopt the same audience binding — not required, but produces sub-issues humans can pick up cold.

Notes

• No local/framework.config.yaml changes. No new opt-out keys — the discipline is LLM self-review against the schema, same machinery as the existing doc-authoring protocol.
• Existing open issues / sub-issues NOT retroactively rewritten (D14 reporter-content forbidden upheld; forward-only convention).
• Full spec: migrations/schema-enforcement-and-human-audience.md.

ginee v0.24.0

Highlights

• Tier 3 compliance closes out the maximum-force Claude playbook (#176). Recency-optimisation pass on the always-loaded surface, six deterministic-template slash commands, main-thread permission lockdown, session-resume injection, and a consent-required attestation gate — the strongest pattern available without a programmatic supervisor.
• Five hard constraints now appear at the top and bottom of CLAUDE.md (T9). Self-lint marker, SA-never-edits, context-economy trailer, D-free runtime, local/**-only-via-discovery — they survive recency drift on long sessions because LLMs read first/last more carefully than the middle. Spec: migrations/claude-md-bookending.md.
• Six slash commands replace LLM free-form composition for drift-prone surfaces (T10): /ginee-dispatch <role> <task> · /ginee-phase-report · /ginee-self-lint · /ginee-commit · /ginee-pr · /ginee-issue-pickup #N. Each lands the schema skeleton at composition time — deterministic by construction. Spec: migrations/slash-commands-suite.md.
• Main-thread permission lockdown forces real work through cardinals (T11). .claude/settings.json § permissions.deny blocks framework-side Edit / Write / MultiEdit + destructive Bash from the main thread; adopter project code untouched. Per-issue warm registry adds a local/framework.config.yaml § warm-reuse.dispatch-cap: 15 soft cap — over-cap triggers fresh-spawn + ## Carry-forward summary payload so the new agent inherits prior decisions instead of starting blind. Spec: migrations/warm-cardinal-default.md.
• SessionStart hook injects [ginee:resume] with current issue/<N>-… branch state + open ginee:in-progress GitHub issues (T12). Quiet on empty; offline-safe — defeats the "start fresh and re-decide everything" pattern across session boundaries. Spec: migrations/session-start-hook.md.
• Optimized-By trailer attestation gate (T13, ask-mode, push-time). When git push would push a range carrying Optimized-By: ai-engineer trailer without a verifiable Agent(subagent_type=ai-engineer) dispatch in the session transcript, Claude Code surfaces its native permission prompt; user picks allow (cross-session work · manual lossless pass · WIP push) or deny (cancel + dispatch first). Closes the voluntary-compliance loophole on the context-economy trailer. Spec: migrations/optimized-by-attestation.md.

Adopter migration

Just run /ginee-update. All five tactics land idempotently — installer copies the six slash commands to .claude/commands/; sync-claude-settings.{ps1,sh} wires SessionStart + attestation hook entries + framework-scoped permissions.deny rules; pointer block in your CLAUDE.md gets the bookend on re-paste.

Per-change action

Change	Action
CLAUDE.md bookending (T9) · slash commands (T10) · SessionStart (T12) · Optimized-By attestation (T13)	None — /ginee-update lands all four.
Main-thread permission lockdown (T11)	None — permissions.deny merges idempotently. Adopter project code is untouched (deny rules are framework-scoped to .agents/ginee/{core,adapters,extras}/**).
Warm-registry dispatch cap	Optional — set warm-reuse.dispatch-cap: <N> in local/framework.config.yaml to override the default 15.

Notes

• Per-tactic opt-out: local/framework.config.yaml § compliance.disabled: [slash-commands | main-thread-permissions | session-start-hook | optimized-by-attestation]. Bypass per call: SKIP_GINEE_COMPLIANCE=1.
• T11 ships adopter-template only. The framework-self-dev .claude/settings.json does NOT get the lockdown — framework devs continue to edit core/** directly. Adopters' deny rules are scoped to .agents/ginee/{core,adapters,extras}/** so their own code is untouched.
• T13 introduces a new force-class axis — consent-required gate (Class A nuance) alongside the existing binary allow/deny gates. The permission prompt is judgment-bearing; legitimate cases (cross-session optimization · manual lossless pass · WIP push) map naturally to "allow."
• Other adapters (Cursor / Copilot / Codex / generic) ship Claude-only for the playbook batch — permissionDecision: "ask", slash commands, and SessionStart all rely on Claude-specific surfaces. Cross-adapter ports follow when their tooling matures.

ginee v0.23.0

Highlights

• Charter rules now enforced at every turn boundary, not just on edits (#173). Four new Claude Code hooks complete the compliance playbook's prompt-time / action-time / turn-time enforcement surface. Less drift on long tasks; warm cardinals stay in their lane across multi-dispatch spans.
• Task keywords (pick up #N · auto: · triage · @<role> · …) auto-inject the relevant spec excerpt before the LLM sees your prompt — no more forgotten gh fetches or skipped scoring labels. T5 spec: migrations/user-prompt-submit-hook.md.
• The framework refuses to end the turn while work is incomplete — missing self-lint marker, PR opened without acceptance, or open ginee:in-progress issue without Phase-8 close. Anti-loop guard means you'll never get trapped. T7 spec: migrations/stop-hook.md.
• Warm-cardinal continuations now require a [carry-forward] Remember: … rule anchor — kills the slow drift away from charter rules over 5–10 reuse cycles. T8 spec: migrations/carry-forward-injection.md.
• All four hooks auto-wire via /ginee-update. Per-tactic opt-out for adopters who want it (user-prompt-submit-hook · posttooluse-edit-hook · stop-hook · pretooluse-send-message-hook); emergency bypass with SKIP_GINEE_COMPLIANCE=1.

Adopter migration

Just run /ginee-update. The four new hooks merge idempotently into your .claude/settings.json alongside the Tier 1 hooks already there; adopter customisations (statusLine override, non-ginee PreToolUse entries) are preserved.

Per-change action

Change	Action
UserPromptSubmit (T5) · PostToolUse self-check (T6) · Stop (T7) · SendMessage anchor (T8)	None — /ginee-update wires all four.
Bash hook ports	None — pwsh 7+ remains the primary; bash ports activate automatically if jq is on PATH.
Per-cardinal carry-forward rules	None — defaults shipped in adapters/claude/hooks/carry-forward-rules.yaml. Customise per-cardinal by editing that file in your own checkout.

Notes

• Other adapters (Cursor / Copilot / Codex / generic) have no UserPromptSubmit / Stop / SendMessage hook surface today — Tier 2 lands Claude-only. Cross-adapter ports ship as their tooling matures.
• Bash hooks degrade fail-open without jq. Pwsh hooks have no such dependency; the bash ports exist for adopters who don't run pwsh 7+ on their CI / dev hosts.

ginee v0.22.0

Highlights

• Per-role context: −19 to −28% (#171). ai-engineer cross-iteration dedup pass — hundreds of feature iterations had introduced cross-file overlap without dedup checks. Every cardinal's per-dispatch load is now substantially smaller; ai-engineer 25k → 18k bytes (−28%) · team-lead 73k → 57k (−22%). Headroom against per-role ceilings goes from 19–37% up to 36–55% in the same release.
• Ceilings tightened to lock in the gains. scripts/templates/role-context-ceilings.json adjusted to ~30% headroom on the new (post-dedup) baseline. Future ordinary edits can grow context by ~30% before tripping the ai-engineer dispatch gate; loosening any ceiling continues to require ai-engineer review per docs/RELEASE.md step 3.
• Two new shared files cut role-kernel + adapter-install boilerplate — core/protocols/role-kernel-shared.md (7 cited sections absorbed from each role kernel) + adapters/_shared/install-common.md (4 cited sections absorbed from each adapter install.md).
• Template ↔ schema pairs merged. sub-issue-dispatch.md ↔ sub-issue-dispatch-schema.md and pr-comment-cadence.md ↔ review-cycle-schema.md consolidated. Schema sidecars retained as thin pointers — existing cross-references resolve unchanged.
• YAML frontmatter parse failure fixed for 4 pre-existing files. description: values containing : (which strict YAML parsers read as nested mappings) converted to folded-block scalar (>-). Surfaced when picked up by a stricter adopter parser; fixed forward.

Adopter migration

Nothing to do. Purely additive on the adopter side; local/* untouched; all @<role> + skill phrasings unchanged; old schema-sidecar paths still resolve via thin-pointer redirects. Re-run /ginee-update (or the bootstrap one-liner) to pick up the new shared files.

Per-change action

Change	Action
Shared role-kernel / install boilerplate (role-kernel-shared.md + install-common.md)	None — kernels + install.md cite the new files automatically.
Template+schema pair merges (sub-issue · review-cycle)	None — schema sidecars now thin pointers; existing cites resolve.
Tightened per-role ceilings	None for adopters — gate fires against framework-self-dev PRs only.
YAML frontmatter fixes	None — /ginee-update picks the corrected files up.

Notes

• Per-role context table. New baselines + headroom (post-tightening):

  Role	Bytes	Ceiling	Headroom
  ai-engineer	18,231	26,000	~30%
  qa-engineer	26,374	38,000	~31%
  backend-engineer	28,079	40,000	~30%
  frontend-engineer	28,148	40,000	~30%
  devops-engineer	32,059	46,000	~30%
  solution-architect	37,255	53,000	~30%
  team-lead	57,305	82,000	~30%

• Audit methodology. Five parallel Explore agents audited disjoint file clusters (schemas+templates · skills · phase+protocols · doc-family · extras+adapters); each returned a structured dedup report; the 11-cluster merge plan synthesised from their findings.

• Skill files preserved. ginee-file-{bug,feature} / ginee-file-framework-{bug,feature} left as 4 separate files per the merge-plan review — cheat-sheet phrasings stay stable for adopters.

ginee v0.21.0

Highlights

• Sub-issue pickup is cheaper (#152). Picking up a sub-issue with a ginee:role:* label + dispatch-contract body dispatches the named cardinal directly. Saves one full @team-lead re-derive (~15–40k tokens) per sub-issue pickup.
• Trivial scope skips Phase 1–3 (#153). New lite: (alias direct:) prefix elides requirements / design / design-review for typos, single-label tweaks, and single-doc-bullet edits. Phase 4 dispatches one named cardinal directly; Phase 7 + Phase 8 still run. CR / ADR gates stay in effect — lite is orchestration cost, not governance bypass. Composes with every other prefix (auto: lite:, branch: lite:, etc.).
• Heavy roles run on demand across Phase 4–7 (#162). team-lead + solution-architect are invocation-gated, not phase-gated — default is skip unless an affirmative trigger fires (sub-issue routing artefact · SA-owned-file edit · NFR-oracle red · ## Open issues / ## Hand-off / Status: In-progress on cardinal return · cross-domain bug · multi-cardinal PR). Phases 1 / 2 / 3 / 8 (team-lead) and 1 / 2 / 7 (SA) stay load-bearing.
• QA pixel-check — mockup becomes a runtime oracle (#163). Optional Phase 5 stage diffs the rendered app against the mockup at a shared seed-state. Catches CSS regressions, layout shifts, missing icons, broken responsive breakpoints — failures behaviour tests + manual smoke miss today. Off by default; opt in via qa.pixel-check.enabled: true. Adopter picks alignment direction (mockup-follows-seed or seed-follows-mockup).

Adopter migration

Mostly nothing to do. The four features are either purely additive or opt-in.

Per-change action

Change	Action
Sub-issue pickup fast-path	None — ginee-pick-up detects the routing artefact and uses it automatically
Lite mode prefix	None — prefix lite: / direct: on any task to use it; otherwise default Phase 1–8
Heavy-role bypass codification	None — codifies an existing principle. Cardinals continue to fill ## Open issues / ## Hand-off / Status fields per phase-report schema; those fields are now the binding re-entry signal
QA pixel-check	Opt in. Set qa.pixel-check.enabled: true in local/framework.config.yaml + populate seed-script.path · mockup-snapshot.path · app-render.command in local/bindings.md. Run the tolerance-bootstrap recipe in the migration to establish baseline masks

Notes

• Heavy-role bypass is enforcement + observability, not new mechanics. Half the rules already existed in fragmented form (SA "governance dip" qualifiers in phase-4/5/6.md, "Review on architectural fix" in phase-6.md, sub-issue pickup fast-path from #152). The shared protocol consolidates them and adds transcript-grep recipes for spotting defensive dispatch.
• Pixel-check pairs with blueprint-diff-protocol.md — blueprint-diff catches mockup self-drift; pixel-check catches app-vs-mockup drift. Both run only on changes touching the visual surface.
• Team-lead headroom drops to ~19% (vs ~23% in 0.20.0). Driven by lite-mode + heavy-role-bypass citation blocks; still within the 90,000-byte ceiling. Watch in 0.22.0 — next dispatch.md-touching change may warrant an ai-engineer pass.

Migration files

• migrations/sub-issue-fast-path.md
• migrations/lite-mode.md
• migrations/heavy-role-bypass.md
• migrations/qa-pixel-check.md

Browse: github.com/kostiantyn-matsebora/ginee/tree/v0.21.0/migrations/.

ginee v0.20.0

Highlights

• Compliance playbook tactics 1–4 (#135). Four hard / visible gates ship on the Claude adapter — promotes the most-violated charter rules from advisory text to action-time enforcement.
• T1 — subagent tools: whitelist (#137). solution-architect cannot Edit / Write; ai-engineer cannot Bash. Binary tool gate at the subagent level; both rules previously lived only in charter text.
• T2 — PreToolUse hook on Edit / Write / MultiEdit (#138). Blocks 5 violation classes at the tool-call layer — hot-spec frontmatter omission · cap-bytes overrun without Optimized-By trailer · D<N> token re-introduction on core/** · always / never / binding / mandatory as rule modifier · always-loaded surface bloat.
• T3 — PreToolUse hook on Bash (#139). Blocks 4 destructive shell patterns — git commit --no-verify · git push --force on main / master · git reset --hard (with SKIP_GINEE_COMPLIANCE override) · gh pr create without --body / --draft.
• T4 — compliance statusline (#140). Single line in Claude Code's status row surfaces issue # · trailer status · cap-bytes headroom on the tightest hot-spec file. Class G — visible state, no enforcement.
• /ginee-update auto-wires T2 / T3 / T4 entries (#160). Adopter .claude/settings.json is merged idempotently — PreToolUse hooks + statusLine block — without manual paste. Adopter customisations (other top-level keys, non-ginee statusLine) are preserved.
• Per-tactic opt-out — local/framework.config.yaml § compliance.disabled: [<tactic-id>] disables individual tactics. Per-invocation bypass: SKIP_GINEE_COMPLIANCE=1 (emergency only).

Adopter migration

Mostly nothing to do. /ginee-update lands the hook scripts, statusline, and wires the entries into .claude/settings.json automatically.

Per-change action

Change	Action
T1 — tools: whitelist	None — tools: line ships inside the pointer subagent files the installer already copies
T2 — Edit/Write hook	None — /ginee-update adds the PreToolUse entry; bash adopters need jq on PATH
T3 — Bash hook	None — same auto-wire path
T4 — statusline	None — statusLine block added to .claude/settings.json automatically

Notes

• Bash-only adopters must have jq on PATH for the settings.json auto-merge. Without it, the sync step warns and skips; the manual snippet in adapters/claude/install.md § Compliance hooks is the fallback.
• Custom statusLine — already-set, non-ginee statusLine.command values are never overwritten. Adopters who want ginee's keep their custom; opt-out via compliance.disabled if you don't want the framework's installed at all.
• Disabling a tactic stops enforcement but leaves the settings.json entry in place. Delete the matching block manually for a clean file.

Migration files

• migrations/cardinal-tools-whitelist.md
• migrations/pretooluse-edit-hook.md
• migrations/pretooluse-bash-hook.md
• migrations/compliance-statusline.md
• migrations/claude-settings-auto-merge.md

Browse: github.com/kostiantyn-matsebora/ginee/tree/v0.20.0/migrations/.

ginee v0.19.0

Highlights

• Index-first reads now binding. Cardinals consult local/index/ summaries first; raw source reads require justification.
• CR/ADR gating + opt-out (D45). Adopters with issue-as-CR stop getting redundant CR drafts; ADRs gated on architectural delta.
• cr.skip-when-issue-source: true is the new default. Pre-cutover behaviour preserved via one named opt-back in local/framework.config.yaml.
• Per-task governance prefixes. cr: / nocr: / adr: / noadr: combine with auto: / branch: / model: / notrack:.
• core/ taxonomy flatten (D46). 12 legacy protocol files relocated under core/protocols/. /ginee-update lands the moves wholesale.
• Hot-spec frontmatter (D47). Every framework spec declares load contract — audience · load · triggers · byte cap · dependencies.
• Validator on missing frontmatter. Hot-spec edits without frontmatter fail CI; same Optimized-By trailer bypass as existing gates.
• RFC 2119 keywords (D48). New framework content uses MUST / SHOULD / MAY; less binding-strength ambiguity for LLM + reviewers.
• Output-schema sidecars (D49). Five new specs — dispatch prompt · sticky score · audit comment · sub-issue dispatch · review cycle.
• Per-role context up ~5–10%. Team-lead headroom drops to ~23%; solution-architect crossed +10% threshold. See docs/reference/CONTEXT_COSTS.md.

Adopter migration

Mostly nothing to do. /ginee-update lands D45–D49 spec changes + D46 file moves wholesale.

Per-change action

Change	Action
Index-first read order	None — applies on next cardinal dispatch
D45 CR/ADR gating	One named default change — cr.skip-when-issue-source: true. Set false to preserve pre-cutover behaviour.
D46 core/ taxonomy flatten	None if you don't cite framework paths in local/. If you do — run the sed snippet in the migration.
D47 hot-spec frontmatter	None — /ginee-update lands frontmatter + validator together
D48 RFC 2119 keywords	None — forward-only; existing rules stay as-written until next edited
D49 output-schema sidecars	None — purely additive

Migration files

• migrations/index-first-read-order.md
• migrations/change-governance-opt-out.md
• migrations/core-taxonomy-flatten.md
• migrations/hot-spec-frontmatter.md
• migrations/rfc2119-keywords.md
• migrations/output-schema-sidecars.md

Browse: github.com/kostiantyn-matsebora/ginee/tree/v0.19.0/migrations/.

ginee v0.18.0

Highlights

• Lighter install — .agents/ginee/ drops the shipped migration directory (~228 KB / 36 files); pre-existing installs clean up on first update.
• Per-item migration approval — /ginee-update now surfaces each migration with a yes / skip / all-yes / all-skip prompt before applying anything.
• Always up-to-date — migrations stream from upstream at update time; no stale local copies to chase, no version skew.
• Cleaner framework rules — ginee files cite their own specs by location; the LLM no longer follows opaque decision-number breadcrumbs.
• Offline-safe — migration fetch failure surfaces inline with the upstream URL; never blocks the update; framework files already landed.
• Warm reuse now actually works on Claude — pre-D43 the 15–50 k token / task savings were silently never realised; the env-var prereq is documented and skill-runner owns the plumbing on Claude.
• Set the env var once and restart — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json unlocks SendMessage; without it Claude falls back to fresh-spawn.
• Lower bills on every Claude task — kernel + role-details + process + index reads survive across dispatches in one task; only first dispatch pays full reload.
• Per-class doc-size caps — ADR ≤ 4 KB · CR ≤ 6 KB · UI ≤ 4 KB by default; raise / lower / opt out per class in local/framework.config.yaml.
• ai-engineer dispatched automatically on bloat — breach the cap, dispatch the optimizer, ship with the trailer bypass — no more silent doc-class drift.
• Forward-only — existing oversized docs surface on next touch; no retroactive sweep.

Adopter migration

Nothing to do. On your next /ginee-update, the installer drops <fw>/core/MIGRATIONS/ mechanically. Subsequent updates fetch migrations from upstream and prompt you to apply each one.

Want to browse migrations as files? They live at github.com/kostiantyn-matsebora/ginee/tree/main/migrations/ (or the equivalent under your github.framework-repo if you've set it).

Filename change. Migration files dropped their D<N>- prefix — they're now named by content slug (installer-fetch-on-update.md, model-tier.md, …). If you bookmarked old paths, the github redirect won't help; use the tree listing to find what you need.

Feature	What you'll notice
Prune	<fw>/core/MIGRATIONS/ removed on next install or update.
Per-item gate	/ginee-update prompts before applying each migration. skip always honored.
Offline behaviour	Migration fetch failure surfaces inline with the upstream URL; update doesn't block.
Runtime cleanup	Framework files (core/, adapters/, extras/) no longer cite D<N> IDs internally. Adopter-facing docs + release notes keep design-history references.

Per-class doc-size caps — D44

Nothing to do if you don't track ADRs · CRs · UI docs. Defaults apply silently to absent class directories; no breach can fire.

To enable enforcement, set the directory keys + (optionally) override caps in local/framework.config.yaml:

adr-directory: docs/adr/
cr-directory: docs/cr/
ui-directory: docs/ui/          # new key

# Optional — override framework defaults (ADR 4096 / CR 6144 / UI 4096):
doc-size-caps:
  adr:
    cap-bytes: 6144              # raise
  # ui: disabled                 # or opt out for a class

The existing context-economy gate (Claude Code hook · git hooks · CI workflow) picks up the per-class check automatically. Breach without Optimized-By: ai-engineer trailer fails the gate — same bypass machinery as the existing whole-PR threshold check.

Existing oversized docs — forward-only. Breach surfaces on the next touch; no retroactive sweep.

Warm reuse on Claude — D43

One-time setup. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and restart Claude Code:

// .claude/settings.json (project) or ~/.claude/settings.json (global)
{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}

That unlocks the SendMessage tool. Without it warm reuse silently falls back to fresh-spawn on every dispatch — which is what was happening pre-D43, even with warm-reuse.enabled: true.

Don't want / can't set the env var? Add warm-reuse.enabled: false to local/framework.config.yaml and accept fresh-spawn cost.

What changed under the hood. Registry ownership on Claude moved from team-lead (impossible — team-lead is a subagent without SendMessage) to the skill-runner (main thread; durable across the task). Team-lead still decides every warm-vs-fresh on every dispatch; only the plumbing moved. Full architecture: adapters/claude/install.md § Warm specialist reuse.

Per-role context cost

Modest growth across cardinals from the D43 core/process/dispatch.md surface-boundary additions + the D44 cross-ref row in core/process.md § Documentation style. team-lead +2.3% bytes (62,232 → 63,694; ~30% headroom on the 90 KB ceiling); other cardinals +0.9–2.7%, all > 38% headroom. No ceiling breach; no rebudget. Full snapshot: reference/CONTEXT_COSTS.html.

Full specs:

• migrations/migrations-upstream-only.md
• migrations/warm-reuse-claude-plumbing.md
• migrations/doc-size-caps.md

Full Changelog: v0.17.0...v0.18.0

ginee v0.17.0

Highlights

• Catch silent mockup regressions — Phase 4 dispatch diffs your mockup vs origin/main and prompts on unexpected deltas. (D41)
• Configurable visual source-of-truth — point the gate at Figma · image baselines · video · adopter-supplied diff tools. (D41)
• Zero-config upgrade — adopters with mockup: set get the gate on next dispatch with no edits to local/framework.config.yaml. (D41)
• Auto-mode honours the gate — unexpected deltas always prompt; the framework never silently re-scopes for you. (D41)

Adopter migration

Nothing to do if you already have mockup: configured — the gate auto-derives defaults (type html-mockup · blueprint origin/main · block-glob scoping) on next Phase 4 dispatch.

Want to override? Add a visual-source-of-truth: block:

# local/framework.config.yaml
visual-source-of-truth:
  type: html-mockup           # html-mockup | figma | image | video | other
  path: docs/mockup.html
  blueprint-ref: origin/main  # or v1.2.0, snapshot path, Figma version URL
  scope-discriminator: block-glob
  enabled: true

Want to opt out? Set enabled: false on the block above.

Feature	What you'll notice
D41 blueprint-diff gate (Phase 4 dispatches touching the visual SoT)	Diff vs blueprint surfaces in the dispatch return; unexpected deltas → forced-interactive gate before edits begin.

Per-role context cost

frontend-engineer gained one row in § Mockup ownership; core/process.md gained one entry in the load-on-demand index; D41 protocol + migration are load-on-demand (no always-loaded cost on non-frontend cardinals). Full snapshot: reference/CONTEXT_COSTS.html.

Full spec: D41.

Full Changelog: v0.16.0...v0.17.0