ADR 0004: Weekly development deck authority and transition

• Status: Proposed; merging the pull request that carries this ADR records acceptance
• Date: 2026-10-24
• Owners: Weekly development report owner (@fmuia) with the dev meeting; HSSMeister's governor owns the production-runtime changes
• Scope: the weekly development deck's evidence authority, ClickUp transition, required model synthesis and human content-and-style gate; not the roadmap sync implementation or a business report

Decision summary

1. Authority is assigned per kind of fact. GitHub is authoritative for development execution facts: repositories, pull requests, issues, reviews, checks and releases. ClickUp is authoritative for the roadmap hierarchy and project-management facts it owns. The report reads each fact from its owner rather than treating either system as a complete copy of the other.
2. The report has a transition mode and a ClickUp-complete mode. During the transition, GitHub guarantees complete development coverage. ClickUp organises explicitly linked work, and every unlinked GitHub record remains visible as not yet represented in ClickUp. Later, ClickUp becomes a superset: every in-scope GitHub record is represented there, alongside ClickUp-only project-management work. Moving between modes changes validation policy, not the report architecture.
3. A provider-neutral work graph joins the observations. Independent, read-only collectors produce versioned GitHub evidence and a versioned ClickUp hierarchy snapshot. A deterministic reconciliation step joins them only through explicit relationships and reports mapped, unmapped, ambiguous, stale and ClickUp-only records.
4. Model synthesis is required editorial work, not optional commentary. A successful report contains a validated, structured editorial analysis that explains material changes, cross-thread dependencies, risks, decisions and recommended priorities. Its factual claims cite evidence records. Failure to produce valid synthesis prevents publication of the final deck.
5. Deck content and visual style have their own human-approved contract. A dedicated review step, after evidence reconciliation and before the model contract or composer, records the intended audience, narrative, recurring sections, information density, voice, visual language, charts, accessibility requirements and worked examples. The model prompt, output schema and renderer implement that specification; they do not invent it.
6. Rendering remains deterministic and bounded. The model chooses emphasis and proposes the narrative within the approved specification. Validation enforces evidence references, required coverage and size limits, and a deterministic renderer produces the artifacts.

Context

The weekly development report currently combines three concerns that are changing at different speeds:

• GitHub contains the complete observable development record.
• ClickUp is becoming the roadmap and project-management surface, but its representation of GitHub work is not complete while the integration is being revised independently.
• The report's model output is currently treated as commentary that can fall back to a generic result, even though the useful product is the synthesis of evidence into a meeting narrative.

The committed report implementation also reads the Git-backed roadmap schema directly. That makes the deck sensitive to roadmap-file structure and to the implementation of the ClickUp synchronization path. It cannot represent the intended transition honestly: using GitHub alone loses project-management work, while treating today's ClickUp view as complete can hide development activity.

This ADR governs what the deck observes and how it declares success. It does not decide how Git and ClickUp synchronize, which fields the synchronization engine writes, or where a future business roadmap lives. In particular, it does not supersede ADR 0002's roadmap decisions. The report consumes observable records and explicit relationships exposed by that separate system.

Authority by field

Information	Authority during transition	Authority in ClickUp-complete mode
Pull request, issue, review, check and release facts	GitHub	GitHub
Completeness of the development evidence set	exact GitHub report scope	ClickUp coverage invariant, verified against the same GitHub scope
Roadmap hierarchy and display order	ClickUp when observed; missing links do not remove GitHub evidence	ClickUp
Priority, assignment, PM status, dependencies and PM-only work	ClickUp	ClickUp
Relationship between a GitHub record and ClickUp work	explicit observed link; otherwise unmapped	explicit observed link; absence is a coverage failure
Interpretation, risks, decisions and meeting priorities	required evidence-grounded model synthesis	required evidence-grounded model synthesis
Content, voice and visual design	approved deck content-and-style specification	approved deck content-and-style specification

ClickUp being a superset does not make a copied pull-request status authoritative. A ClickUp task may represent or aggregate GitHub records, but the report still reads their current state from GitHub.

Transition contract

Transition mode

The report must:

• gather every record in the exact development-report GitHub scope;
• read the configured ClickUp hierarchy independently when a current or permitted last-known snapshot is available;
• place explicitly linked GitHub work under its ClickUp location;
• place unmatched GitHub work in a visible Not yet mapped in ClickUp section;
• keep ambiguous relationships visible and attach them to no location until a person or the owning integration resolves them;
• include ClickUp-only work as project-management evidence, clearly distinguished from GitHub execution evidence; and
• publish reconciliation counts and provenance with the deck.

A missing or stale ClickUp snapshot may degrade organisation during the transition, subject to a documented freshness budget, but it may never reduce GitHub coverage. The deck labels the degraded state instead of silently using the Git-backed roadmap as a substitute.

ClickUp-complete mode

The report changes mode only through a reviewed configuration change after all of these hold for a defined observation period:

• every in-scope open GitHub pull request and issue is explicitly represented by one ClickUp task or one declared aggregate task, or has a reviewed exclusion;
• no ambiguous relationships remain;
• missing, duplicate and stale representations are monitored;
• ClickUp-only tasks render without requiring a GitHub record;
• the ClickUp hierarchy and display order are stable inputs to the deck; and
• representative decks have passed human content and visual review.

In this mode a missing or over-age ClickUp snapshot is a report failure. GitHub is still queried directly for GitHub-native facts.

Work-graph and reconciliation contract

The report uses versioned observations rather than allowing the composer to query provider-specific files or APIs. At minimum the graph preserves:

• stable provider identifiers, URLs, timestamps and source revisions;
• the ClickUp Workspace, Space, Folder, Subfolder, List, Task and Subtask ancestry that is actually present;
• the exact GitHub repository and record identity;
• explicit relationship type and provenance;
• provider-owned status and ownership without merging fields that have different meanings; and
• whether a record is mapped, unmapped, ambiguous, stale, excluded or ClickUp-only.

The reconciliation engine may consume a versioned relationship artifact from the separately owned integration. It must not depend on that integration's internal roadmap schema, branch, proposal workflow or implementation language. Title similarity or model inference can suggest a relationship for human review, but cannot establish one for published evidence.

Required editorial analysis

The report replaces free-form optional commentary with a structured editorial artifact. Its reviewed schema must cover at least:

• an executive assessment;
• material changes and why they matter;
• cross-repository and cross-thread dependencies;
• risks and blockers;
• decisions required;
• recommended priorities and meeting agenda;
• proposed emphasis and ordering inside the approved deck structure; and
• evidence references for factual claims.

The model may rank, connect and explain source facts. It may not change their provider-owned state, hide required evidence, or assert an unverified GitHub–ClickUp relationship. Schema validation, reference validation and content guards run before rendering.

If valid synthesis cannot be produced after bounded attempts, the workflow retains its evidence, reconciliation and diagnostic artifacts and may render an internal diagnostic draft. The run is failed and no final weekly deck is published. A deterministic fallback is an operational aid, not successful report completion.

Human deck content-and-style gate

Implementation deliberately pauses before the editorial schema and composer. The report owner supplies and approves a versioned deck specification in its own pull request. It defines:

• audience, meeting purpose and the decisions the deck should support;
• the narrative arc and required, optional and forbidden sections;
• how ClickUp hierarchy, unmapped GitHub work and PM-only work appear;
• what the model selects, writes, recommends and must leave verbatim;
• tone, terminology, headline and annotation rules;
• slide count, information density and overflow policy;
• layout, typography, colour, chart and diagram rules;
• accessibility and projection/readability requirements;
• representative input/output examples and visual acceptance cases; and
• which changes require renewed human approval.

The approved specification is a versioned runtime input and its revision or digest appears in the report receipt. Updating it is a separately reviewable product decision, not an incidental composer or CSS edit.

Options considered

GitHub-only deck until the transition ends

This is operationally simple and preserves complete development evidence, but it hides the emerging roadmap hierarchy and cannot include ClickUp-only project-management work. It also creates a second migration later. Rejected as the target architecture.

Treat ClickUp as complete immediately

This produces the desired eventual hierarchy quickly, but missing relationships can silently omit valid development work while the integration is changing. Rejected during the transition.

Merge GitHub and ClickUp heuristically in the composer

This avoids a separate contract but makes provenance, ambiguity and omissions hard to review. It also couples rendering to the synchronization implementation. Rejected.

Staged authority with explicit reconciliation

This adds a work-graph and coverage step, but it makes incompleteness visible, keeps provider authority intact and allows the eventual cutover to be a policy change. Accepted.

Consequences

• GitHub remains the completeness backstop while ClickUp is populated.
• ClickUp can contain non-code work without manufacturing GitHub records.
• The synchronization implementation can change without requiring a report rewrite, provided it preserves or versions the relationship contract.
• Report generation gains explicit observation, reconciliation, editorial and rendering stages, with more artifacts to validate and retain.
• A model outage prevents final publication; bounded retries, useful runtime diagnostics and an operational recovery path therefore become release requirements.
• Composer work cannot be approved until the report owner supplies the deck content-and-style specification.
• Historical decks remain reproducible from their evidence, ClickUp snapshot, reconciliation result, editorial artifact and specification revision.

Implementation sequence

Each numbered item is a separately reviewable change. No implementation change belongs in the pull request carrying this ADR.

1. Define and validate the provider-neutral work-graph schema and fixtures.
2. Adapt the complete GitHub evidence into the graph without changing the published deck.
3. Add a read-only ClickUp hierarchy reader with recorded API fixtures and no production credential.
4. Add deterministic reconciliation and coverage reporting; do not change the deck yet.
5. Review and approve the dedicated deck content-and-style specification.
6. Define the required editorial-analysis schema, prompt and evidence validation from that specification; exercise it in shadow mode.
7. Add the transition composer behind a feature flag.
8. Define and validate the vendored report-runtime boundary.
9. Run the new pipeline in HSSMeister beside the current publication path.
10. Cut production publication over in a configuration-only change after evidence, analysis and visual review.
11. Change to ClickUp-complete policy in a later configuration-only review when the coverage gates above have held.

Independent renderer-security fixes may land separately because they do not change source authority, reconciliation, editorial policy or deck content.

Non-goals

• Designing or changing the GitHub–ClickUp synchronization algorithm.
• Deciding whether development and business work use one or several Spaces.
• Defining the actual slide content or visual language in this ADR.
• Treating model output as evidence.
• Inferring that two records are related because their text is similar.
• Building a business report.