Add roadmap-impact reconciliation as a completion hook for repository-changing agents

[szmyty]

Outcome

Add a reusable roadmap-maintenance workflow to Aether and integrate it into the shared completion contract for repository-changing agents so every pull-request handoff evaluates whether the completed work changed roadmap truth.

The goal is not to force a roadmap edit on every PR. The goal is to make roadmap drift difficult to accumulate silently.

Existing foundation

Aether already owns:

• architecture-roadmap — the roadmap document specification;
• create-roadmap-document — the roadmap authoring/update skill;
• reusable agent contracts and provider projections;
• repository-continuity composition patterns;
• decision-impact / human-governance patterns in adjacent workflows.

This issue should compose those capabilities rather than create another roadmap format.

Completion invariant

Before a repository-changing agent presents a pull request for review, it must evaluate:

Did this change materially alter the repository's strategic roadmap state, dependency relationships, capability horizon, or evidence of roadmap completion?

The result must be one of:

1. Roadmap updated — ROADMAP.md changed because roadmap truth changed.
2. Roadmap impact proposed — a strategic change appears necessary but requires human review before modifying roadmap intent.
3. Roadmap not affected — no roadmap mutation is warranted, with a concise reason.
4. Roadmap check blocked — required roadmap/context evidence was unavailable or contradictory.

Silence is not a valid result.

New reusable skill

Create a focused skill such as:

reconcile-roadmap-impact

or another naming choice consistent with Aether conventions.

The skill should not rewrite the entire roadmap by default. It should:

1. resolve the current ROADMAP.md and governing architecture-roadmap contract;
2. inspect the implemented issue/PR scope and validation evidence;
3. identify linked roadmap step(s), if any;
4. determine whether strategic state actually changed;
5. update only the minimum canonical roadmap content needed when authorized;
6. preserve uncertain or human-governed priority changes as proposals;
7. validate the resulting roadmap;
8. emit a structured roadmap-impact disposition for PR handoff.

When a larger strategic rewrite is needed, delegate to create-roadmap-document rather than embedding duplicate authoring logic.

What counts as roadmap impact

Examples that may require roadmap reconciliation:

• a major capability or phase is actually completed;
• a roadmap initiative becomes blocked/unblocked;
• a prerequisite or dependency materially changes;
• a planned capability is superseded or intentionally deferred;
• implementation proves a strategic assumption false;
• a significant new initiative is accepted through an authorized decision process;
• a release/milestone provides evidence that a roadmap outcome has landed;
• repository responsibility changes materially.

Examples that usually do not require roadmap mutation:

• routine bug fixes within an existing roadmap phase;
• refactors that do not change capability/strategy;
• formatting/docs corrections with no strategic effect;
• tests that merely strengthen evidence for already-current roadmap state;
• implementation details already represented by an existing strategic outcome.

Agent integration

Update the canonical Aether agent contract/composition model so every agent with repository mutation authority performs the roadmap-impact check before PR handoff.

Prefer one shared completion hook/composed skill over copy-pasting instructions into every agent body.

The behavior must be reflected in generated provider projections for supported hosts.

Read-only agents such as the Auditor should not mutate roadmaps merely because they discover roadmap implications. They may emit a proposed roadmap impact for a later authorized workflow.

PR handoff evidence

Define a compact machine/human-readable disposition that can be included in PR summaries, for example:

Roadmap impact: updated
Roadmap step: RELAY-03
Reason: the capability is implemented and validation evidence is linked

or:

Roadmap impact: none
Reason: implementation is bounded maintenance within an already-active initiative

The exact syntax may be refined, but it should be stable enough for future validation/indexing.

Organization-roadmap propagation

Repository agents may identify that a local change also affects an organization-level initiative from egohygiene/hygiene#60.

They should emit a typed organization-roadmap impact signal/reference but must not mutate the organization roadmap unless separately authorized to modify its owning repository/source.

This keeps local PRs bounded while making cross-repository roadmap drift observable.

Human-governed changes

Agents must not silently:

• reprioritize now/next/later horizons;
• move speculative work into committed scope;
• remove initiatives because they seem unnecessary;
• declare strategic completion from incomplete evidence;
• rewrite organization strategy from local implementation activity.

Those changes require explicit authority/evidence and, when consequential, the appropriate ADR or human review.

Validation / evaluations

Add deterministic cases covering:

• roadmap step completed by the PR;
• roadmap step partially advanced but not complete;
• ordinary bug fix with no roadmap impact;
• blocked roadmap check due to stale/missing source;
• proposed reprioritization requiring human review;
• local change affecting an organization initiative;
• read-only agent discovering roadmap impact;
• stale roadmap state detected during handoff;
• provider projection contains the shared hook without duplicated semantics.

Acceptance criteria

• A reusable roadmap-impact reconciliation skill exists.
• It composes architecture-roadmap and create-roadmap-document rather than duplicating them.
• Every repository-changing Aether agent evaluates roadmap impact before PR handoff through a shared composition/hook.
• Read-only agents cannot mutate roadmap state without separate authority.
• Every handoff resolves to updated / proposed / not-affected / blocked rather than silence.
• No-change dispositions require a concise reason but do not fabricate edits.
• Strategic priority/optionality changes remain human-governed.
• Local agents can emit organization-roadmap impact signals without mutating organization strategy directly.
• Generated provider projections preserve the behavior.
• Deterministic evals cover material, non-material, blocked, and cross-repository cases.
• Catalog/distribution/validation checks pass.

Related

• architecture-roadmap specification
• create-roadmap-document skill
• egohygiene/hygiene#60 — organization roadmap contract
• egohygiene/relay#31 — repository /roadmap/ visualization
• repository continuity completion composition

Non-goals

• Updating the roadmap on every single PR regardless of meaning.
• Turning ROADMAP.md into a changelog.
• Letting implementation agents autonomously reprioritize strategy.
• Updating the organization roadmap from arbitrary repository write authority.
• Replacing GitHub issues with roadmap documents.