Add staged weekly reporting

Fan out read-only quest discovery into validated report artifacts and assemble deterministic parent and child issue previews without enabling schedules or repository writes.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: juliamuiruri4

.github/agentic-refresh/README.md

@@ -1,8 +1,10 @@
 # Agentic refresh controls
 
 This directory contains the governance boundary for quest refresh automation.
-Phase 0 established the controls. Phase 1 adds manually dispatched, read-only
-discovery workflows without enabling schedules or repository writes.
+Phase 0 established the controls. Phase 1 added manually dispatched, read-only
+discovery workflows. Phase 2A adds reusable staged reporting, structured
+artifacts, and deterministic parent/child previews without enabling schedules or
+repository writes.
 
 - [`capabilities.json`](./capabilities.json) keeps Buildathon writes disabled
   until the repository-scoped token and dispatch spikes pass. External
@@ -23,22 +25,31 @@ discovery workflows without enabling schedules or repository writes.
 - The five Quest Master profiles under [`../agents`](../agents) fix each quest's
   source and path boundary.
 - The five `discover-*.md` workflows under [`../workflows`](../workflows) run
-  manual Phase 1 audits. Their shared policy permits only read operations and
-  returns reports in the agent response. Every automatic issue path is disabled,
-  and safe-output processing is forced into staged preview mode.
+  manual or orchestrated audits. Their shared policy permits only read
+  operations, and `shared/report-output.md` materializes a validated run-scoped
+  JSON artifact. Every automatic issue path is disabled, and safe-output
+  processing is forced into staged preview mode.
+- `weekly-refresh-orchestrator.yml` fans out to all five reusable compiled
+  workflows only through manual dispatch. `weekly-refresh-digest.md` downloads
+  available quest artifacts, converts missing scopes to blocked results, and
+  uploads deterministic parent and child issue previews.
+- `scripts/weekly-refresh-report.mjs` is the machine-readable authority for ISO
+  week context, schema validation, lifecycle/source/path boundaries, materiality,
+  markers, finding keys, deduplication keys, and preview rendering.
 
 Run the local Phase 0 checks with:
 
 ```bash
 node scripts/validate-refresh-config.mjs
+node scripts/weekly-refresh-report.mjs self-test
 node scripts/validate-content-links.mjs
 mkdocs build --strict
 gh aw compile --strict --validate
 ```
 
-No scheduled or write-capable agentic workflow is enabled. Phase 1 workflows
-cannot be live-trialed through `workflow_dispatch` until their compiled
-definitions are available on the default branch.
+No scheduled or write-capable agentic workflow is enabled. The discovery and
+reporting workflows cannot be live-trialed through `workflow_dispatch` until
+their compiled definitions are available on the default branch.
 
 gh-aw v0.77.5 normally reserves `issues: write` for generated failure-reporting
 jobs even when issue handlers are disabled. Phase 1 additionally sets

.github/agentic-refresh/governance.md

@@ -96,6 +96,23 @@ With staging enabled, the compiled Phase 1 locks contain no repository write
 permission. Phase 2 must deliberately remove staging and revisit permissions
 before enabling real issue reporting.
 
+## Phase 2A staged reporting guard
+
+The weekly reporting layer remains manual-only and report-only:
+
+- the deterministic orchestrator has `workflow_dispatch` but no schedule;
+- all five Quest Master workflows accept reusable `workflow_call` inputs for an
+  ISO week and prior ISO week;
+- the only agent-requested output is a custom job that validates and uploads a
+  run-scoped JSON artifact;
+- the digest tolerates missing quest artifacts by recording the scope as
+  blocked, then creates deterministic parent and child previews as artifacts;
+- no compiled or traditional workflow grants issue, branch, pull-request,
+  workflow-dispatch, or content write permission.
+
+The intended `0 8 * * 1` schedule and real issue safe outputs remain Phase 2B
+activation work and require default-branch trials plus the bounded token spike.
+
 ## SAML authorization
 
 SAML authorization is needed only for local audits and human GitHub operations.

.github/agentic-refresh/report-contract.md

@@ -3,6 +3,22 @@
 Each weekly run produces one digest covering all five quests. It creates a child
 plan only for a material change.
 
+Every quest run first emits one version 1 JSON artifact with:
+
+- ISO week key, prior ISO week key, and exact quest slug;
+- exactly one result: `material-change`, `no-material-change`, or `blocked`;
+- source facts separated from repository observations and proposed changes;
+- lifecycle, allowlisted evidence URL, evidence location, wording, and source
+  fingerprint for every official-source delta;
+- learner impact, owned-path drift, asset impact, report-only CodeTour impact,
+  validation, risks, human decisions, and prior finding keys;
+- deterministic parent key, child key, markers, source fingerprints, and finding
+  keys added by `scripts/weekly-refresh-report.mjs`.
+
+A completed report must include source fingerprints. A blocked report must state
+one concise reason and cannot propose changes. A no-change report cannot propose
+changes. Invalid or missing quest artifacts become blocked scopes in the digest.
+
 A child plan must contain:
 
 1. Quest and ISO week key.
@@ -23,3 +39,13 @@ Reports must distinguish source facts, repository observations, inferred
 impact, proposed changes, and unresolved uncertainty. Search snippets are not
 evidence. No implementation may start from a digest or an unapproved child
 plan.
+
+Phase 2A produces only run-scoped artifacts:
+
+- one validated JSON artifact per successful quest output;
+- one deterministic digest JSON file;
+- one parent issue Markdown preview;
+- one child issue Markdown preview only for each material-change result.
+
+No Phase 2A workflow creates or updates an issue, comment, branch, pull request,
+workflow dispatch, schedule, or content file.

.github/agentic-refresh/tooling.json

@@ -3,5 +3,7 @@
   "ghAwVersion": "v0.77.5",
   "ghAwSetupAction": "github/gh-aw-actions/setup-cli@3ea13c02d765410340d533515cb31a7eef2baaf0",
   "checkoutAction": "actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803",
+  "downloadArtifactAction": "actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c",
+  "uploadArtifactAction": "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a",
   "pythonVersion": "3.12"
 }