Deliver #15 through an ordered repository-journal execution plan

[szmyty]

Outcome

Deliver the reusable repository-journal capability from #15 through an ordered, evidence-gated implementation plan that can be advanced one bounded checkpoint at a time.

The governing architecture is:

immutable Aether contract
        ↓
bounded GitHub evidence
        ↓
isolated agent transformation
        ↓
schema validation
        ↓
deterministic Aether rendering
        ↓
Step Summary + durable artifacts

The agent is never the evidence authority. GitHub evidence is collected deterministically, untrusted repository text remains data, agent output is validated, and the pinned Aether renderer produces the final contract artifacts.

Dependency status

• Relay Define a secure reusable workflow catalog and contract #1 is completed.
• Aether Publish reusable supply-chain evidence, signing, and provenance workflows #44 is completed through feat: add repository journal contract aether#59.
• The Aether repository-journal contract is version 1.0.0 and currently marked draft; Relay may consume it only through an immutable commit and digest.
• No duplicate Relay implementation branch or pull request was found when this plan was created.
• Release publication and movement of the v1 alias are explicitly outside this plan.

Execution rule

Work through one numbered step at a time. Do not advance a later step until the active step has reviewable evidence, its discovered constraints are reconciled, and this issue records the checkpoint. Preserve one bounded implementation line for #15 and avoid unrelated refactors.

Ordered execution plan

• 1. Complete the runtime and authentication preflight

  • Verify whether organization policy permits Copilot requests through the workflow GITHUB_TOKEN.
  • Verify availability and least-privilege use of copilot-requests: write.
  • Define a fine-grained token fallback without requiring it by default.
  • Select an exact, immutable Copilot CLI version and document billing/rate behavior.
  • Fail clearly when no approved authentication mode is available.

• 2. Freeze the Aether dependency

  • Pin the repository-journal distribution from feat: add repository journal contract aether#59 by immutable commit.
  • Record the contract ID, semantic version, source digest, and file checksums.
  • Vendor or otherwise bind only the schema, renderer, template, and metadata required at runtime.
  • Document the upstream draft maturity state without converting it into Relay-owned policy.

• 3. Define Relay's journal contract

  • Define versioned inputs for repository identity, reporting interval, evidence limits, optional sections, and execution mode.
  • Define outputs for Markdown, machine-readable JSON, completeness state, provenance, and checksums.
  • Define explicit complete, partial, unavailable, and failed semantics.
  • Define pagination, record-count, byte, and runtime bounds before provider collection is implemented.

• 4. Build the deterministic evidence collector

  • Collect the required repository activity through bounded GitHub provider calls.
  • Cover merged work, open and stale work, releases, CI, dependency/security signals, risks, blockers, and unknowns.
  • Treat issue, pull-request, commit, discussion, configuration, and log text as untrusted data.
  • Distinguish an observed empty result from unavailable or incomplete evidence.
  • Do not check out or execute consumer repository code.

• 5. Add the isolated Copilot or equivalent agent adapter

  • Expose only bounded evidence, the schema, and governing contract inside an isolated temporary workspace.
  • Grant only the minimum read/write tools required to produce candidate structured output.
  • Do not grant repository mutation, arbitrary Git, release, issue-writing, deployment, or external-delivery authority.
  • Validate generated output and fail closed on malformed, incomplete, contradictory, or oversized results.
  • Keep provider-specific behavior behind an explicit adapter boundary.

• 6. Render the final journal deterministically

  • Pass validated input through the pinned Aether renderer.
  • Produce the final human-readable Markdown and machine-readable JSON artifacts.
  • Record contract version and digest, repository revision, reporting interval, generation timestamp, runner version, and evidence completeness.
  • Bind outputs with checksums and preserve deterministic ordering.

• 7. Compose the reusable and dogfood workflow surfaces

  • Add a reusable workflow_call core.
  • Add a Relay-owned workflow_dispatch and scheduled dogfood caller.
  • Use Relay itself as the canary repository unless stronger evidence requires a separate consumer.
  • Keep Slack, Discord, and other delivery sinks outside the core workflow.
  • Declare minimum permissions, explicit timeouts, concurrency behavior, retention, and failure semantics.

• 8. Add security, failure, and contract tests

  • Cover normal, empty, partial, paginated, truncated, and unavailable evidence.
  • Cover malicious prompt-injection content and secret sentinels.
  • Cover invalid agent output, upstream contract mismatch, provider instability, renderer failure, and artifact retention on blocking failure.
  • Validate permissions, immutable dependencies, timeouts, catalogs, schemas, JSON/YAML, inline shell, and deterministic checksums.
  • Prove that logs and artifacts do not expose tokens, environment values, or unsupported sensitive content.

• 9. Document and catalog the capability

  • Add a minimal consumer example and a Relay dogfood example.
  • Document authentication, organization-policy, cost, rate-limit, recovery, rerun, partial-evidence, and credential-rotation behavior.
  • Update the workflow/action catalogs and their validators.
  • Reconcile architecture, roadmap, decisions, changelog, and continuity records without claiming release publication.
  • Document optional sink adapters as separate future composition surfaces.

• 10. Open and validate one bounded implementation pull request

  • Use one branch and one reviewable pull request for the Publish a reusable scheduled repository journal workflow #15 implementation.
  • Require complete local validation and exact-head GitHub Actions evidence.
  • Perform code, contract, security, and documentation review.
  • Leave merge authority to the user.
  • Do not publish a release or move the v1 alias in this pull request.

• 11. Complete post-merge live acceptance

  • Verify the implementation landed cleanly on current main.
  • Manually dispatch the Relay canary and inspect its Step Summary, JSON, artifacts, provenance, permissions, and sanitized logs.
  • Observe and verify the first scheduled execution through the same implementation path.
  • Record live evidence and any limitations on this issue and Publish a reusable scheduled repository journal workflow #15.
  • Close this execution plan and Publish a reusable scheduled repository journal workflow #15 only after the implementation and live canary evidence are reconciled; keep release publication deferred.

Completion criteria

• Every numbered checkpoint is completed with inspectable evidence.
• The reusable workflow satisfies Publish a reusable scheduled repository journal workflow #15 without embedding mutable Aether policy.
• Agent execution is isolated, least-privilege, bounded, and non-authoritative.
• Manual and scheduled canary executions succeed from the default branch.
• No external delivery service is required.
• No release or moving-alias publication is bundled into this work.

Related

• Parent outcome: Publish a reusable scheduled repository journal workflow #15
• Foundation: Define a secure reusable workflow catalog and contract #1
• Upstream contract: Define the repository journal agent prompt and output contract aether#44
• Upstream implementation: feat: add repository journal contract aether#59
• Reference workflow: https://github.com/lucide-icons/lucide/blob/main/.github/workflows/repo-journal.yml

[szmyty]

Step 1 implementation checkpoint is now available in draft PR #96.

Implemented and locally verified:

• checksum-locked @github/copilot@1.0.85 runtime on Node.js 24
• preferred short-lived GITHUB_TOKEN contract with copilot-requests: write
• explicit, non-automatic fine-grained PAT fallback
• closed runtime-profile and secret-free preflight-result contracts
• fail-closed policy, permission, credential-precedence, version, and billing checks
• one invocation, one attempt, five-minute timeout, and one scheduled run/day bounds
• canonical CI validation, documentation, and 12 focused tests

Published implementation commit: f94eb4f8360e34963953417fadc3919d3a106ae7
Exact current draft head: b7ab8f8515d06d06a55dc3a48329fcf2103dd642

Local validation passed all 368 tests plus catalog, continuity-contract, compilation, JSON/YAML, exact CLI-version, and diff checks. Exact-head GitHub Actions are green:

• Validate Relay actions
• Relay continuity preflight
• Dependency review

The Step 1 checkbox remains open. Before advancing to Step 2, we still need to verify together that the organization permits Copilot CLI requests billed through the workflow GITHUB_TOKEN, confirm the intended permission/billing path, and run the offline secret-free preflight in that context. No live Copilot request or organization-setting change has been made.