Add agentic refresh Phase 0 controls

.gitattributes

@@ -0,0 +1 @@
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Julia is the merge authority; Bethany is the independent fallback reviewer.
+* @juliamuiruri4 @BethanyJep

.github/agentic-refresh/README.md

@@ -0,0 +1,32 @@
+# Agentic refresh controls
+
+This directory contains the Phase 0 governance boundary for future quest refresh
+automation.
+
+- [`capabilities.json`](./capabilities.json) keeps Buildathon writes disabled
+  until the repository-scoped token and dispatch spikes pass. External
+  repositories are permanently report-only under this strategy.
+- [`quests.json`](./quests.json) defines source allowlists, Buildathon ownership,
+  external observation paths, approval identity, branch shape, and operational
+  limits.
+- [`github-token.json`](./github-token.json) defines the built-in
+  `GITHUB_TOKEN` permission and event model without storing a PAT or App key.
+- [`governance.md`](./governance.md) documents the repository settings and
+  technical spikes required before enabling Buildathon write automation.
+- [`lifecycle-policy.md`](./lifecycle-policy.md),
+  [`audience-style-guide.md`](./audience-style-guide.md),
+  [`report-contract.md`](./report-contract.md),
+  [`stack-policy.md`](./stack-policy.md), and
+  [`asset-policy.md`](./asset-policy.md) define the non-negotiable content and
+  workflow contracts.
+
+Run the local Phase 0 checks with:
+
+```bash
+node scripts/validate-refresh-config.mjs
+node scripts/validate-content-links.mjs
+mkdocs build --strict
+gh aw compile --strict --validate
+```
+
+No scheduled or write-capable agentic workflow is enabled in Phase 0.

.github/agentic-refresh/asset-policy.md

@@ -0,0 +1,16 @@
+# Asset policy
+
+Asset work begins with an approved brief and stays inside the quest's owned
+paths.
+
+- Prefer existing assets or text when they explain the step adequately.
+- Use original SVG for static diagrams and Remotion only when motion adds
+  instructional value.
+- Preserve editable source and deterministic rendering commands.
+- Record dimensions, file size, alt text, source files, and render commands in
+  an asset manifest.
+- Verify light and dark readability, current branding, and the absence of
+  credentials or personal data.
+- Use controlled product screenshots and document any manual validation.
+- Keep asset revisions on the same `01-core` branch initially.
+- Stop after two automated revision rounds and request human guidance.

.github/agentic-refresh/audience-style-guide.md

@@ -0,0 +1,16 @@
+# Audience and style guide
+
+Content serves beginner and intermediate JavaScript and TypeScript developers.
+
+- State prerequisites, expected cost, cleanup, and platform limitations before
+  a learner starts a billable or environment-specific step.
+- Prefer a short working path, then use progressive disclosure for optional or
+  expensive exploration.
+- Explain product terms at first use and avoid unexplained architecture jumps.
+- Keep commands and code copyable, language-appropriate, and consistent with
+  the target repository.
+- Separate verified product facts from repository observations and proposed
+  teaching choices.
+- Do not claim a lifecycle, feature, or recommended pattern without an
+  allowlisted citation.
+- Preserve the quest scenario unless an approved plan explicitly changes it.

.github/agentic-refresh/capabilities.json

@@ -0,0 +1,112 @@
+{
+  "version": 2,
+  "defaultMode": "report-only",
+  "lastReviewedAt": "2026-07-24",
+  "repositories": [
+    {
+      "name": "Azure-Samples/JavaScript-AI-Buildathon",
+      "role": "automation-host",
+      "status": "blocked",
+      "writeAutomationAllowed": false,
+      "capabilities": {
+        "repositoryScopedTokenSelected": true,
+        "copilotCodeReviewEnabled": true,
+        "copilotInferenceAvailable": false,
+        "aiCreditBudgetAvailable": false,
+        "repositoryAdministratorAvailable": true,
+        "githubTokenIssueWritesConfirmed": false,
+        "githubTokenPullRequestWritesConfirmed": false,
+        "explicitDispatchChecksConfirmed": false,
+        "refreshBranchCreationAllowed": false,
+        "rulesetConfigured": false,
+        "conversationResolutionRequired": true,
+        "codeOwnerReviewRequired": false,
+        "requiredChecksKnown": true
+      },
+      "requiredChecks": [
+        "validate-content",
+        "validate-agentic-workflows"
+      ],
+      "pendingRequiredChecks": [
+        "copilot-review-gate"
+      ],
+      "approval": {
+        "approvedBy": null,
+        "approvedAt": null,
+        "evidence": null
+      },
+      "auditEvidence": {
+        "copilotCodeReviewWorkflowId": 209015997,
+        "rulesetId": 19622585,
+        "approverVariable": "REFRESH_APPROVER_LOGIN=juliamuiruri4",
+        "labelsConfigured": true,
+        "phaseZeroPullRequest": 110
+      },
+      "blockers": [
+        "The Copilot inference permission and AI-credit budget have not been confirmed.",
+        "A manual trial must prove that GITHUB_TOKEN can create Buildathon issues, refresh/** branches, and pull requests under the organization policy.",
+        "A required-check spike must prove explicit workflow dispatch after GITHUB_TOKEN-created pull requests and branch updates.",
+        "Ruleset 19622585 must be activated after CODEOWNERS and both Phase 0 validation checks are merged and have successful check runs.",
+        "The human-only merge ruleset template must be created or confirmed in repository settings; the REST API returned 404 when user bypass was requested."
+      ]
+    },
+    {
+      "name": "Azure-Samples/serverless-chat-langchainjs",
+      "role": "external-report-only",
+      "status": "report-only",
+      "writeAutomationAllowed": false,
+      "capabilities": {
+        "repositoryScopedTokenSelected": false,
+        "copilotCodeReviewEnabled": true,
+        "copilotInferenceAvailable": false,
+        "aiCreditBudgetAvailable": false,
+        "repositoryAdministratorAvailable": false,
+        "githubTokenIssueWritesConfirmed": false,
+        "githubTokenPullRequestWritesConfirmed": false,
+        "explicitDispatchChecksConfirmed": false,
+        "refreshBranchCreationAllowed": false,
+        "rulesetConfigured": false,
+        "conversationResolutionRequired": false,
+        "codeOwnerReviewRequired": false,
+        "requiredChecksKnown": false
+      },
+      "requiredChecks": [],
+      "approval": {
+        "approvedBy": null,
+        "approvedAt": null,
+        "evidence": null
+      },
+      "policyReason": "Cross-repository writes are intentionally disabled; findings require a manual maintainer handoff.",
+      "blockers": []
+    },
+    {
+      "name": "Azure-Samples/mcp-agent-langchainjs",
+      "role": "external-report-only",
+      "status": "report-only",
+      "writeAutomationAllowed": false,
+      "capabilities": {
+        "repositoryScopedTokenSelected": false,
+        "copilotCodeReviewEnabled": true,
+        "copilotInferenceAvailable": false,
+        "aiCreditBudgetAvailable": false,
+        "repositoryAdministratorAvailable": false,
+        "githubTokenIssueWritesConfirmed": false,
+        "githubTokenPullRequestWritesConfirmed": false,
+        "explicitDispatchChecksConfirmed": false,
+        "refreshBranchCreationAllowed": false,
+        "rulesetConfigured": false,
+        "conversationResolutionRequired": false,
+        "codeOwnerReviewRequired": false,
+        "requiredChecksKnown": false
+      },
+      "requiredChecks": [],
+      "approval": {
+        "approvedBy": null,
+        "approvedAt": null,
+        "evidence": null
+      },
+      "policyReason": "Cross-repository writes are intentionally disabled; findings require a manual maintainer handoff.",
+      "blockers": []
+    }
+  ]
+}

.github/agentic-refresh/capability-matrix.md

@@ -0,0 +1,69 @@
+# Refresh capability matrix
+
+The machine-readable source of truth is
+[`capabilities.json`](./capabilities.json).
+
+- Buildathon stays **report-only** until every same-repository write and dispatch
+  capability is confirmed, approval evidence is recorded, and
+  `writeAutomationAllowed` is explicitly set to `true`.
+- The two external sample repositories are intentionally **report-only** and do
+  not have an automated write-enablement path under this strategy.
+
+| Repository | Role | Current mode | Capability status |
+|---|---|---|---|
+| `Azure-Samples/JavaScript-AI-Buildathon` | Automation host | Report-only | Blocked |
+| `Azure-Samples/serverless-chat-langchainjs` | External evidence | Report-only | Policy |
+| `Azure-Samples/mcp-agent-langchainjs` | External evidence | Report-only | Policy |
+
+## Buildathon confirmation
+
+Before Buildathon write automation is enabled, confirm:
+
+1. Copilot inference works with `copilot-requests: write` and the organization
+   has an available AI-credit budget.
+2. `GITHUB_TOKEN` can create a Buildathon issue through a bounded safe output.
+3. `GITHUB_TOKEN` can create and update only `refresh/**` branches and open a
+   Buildathon pull request through bounded safe outputs.
+4. Explicit workflow dispatch produces every required check for the current head
+   SHA after token-created PRs and subsequent automated updates.
+5. Copilot Code Review can be explicitly requested for the current head SHA.
+6. The main ruleset requires pull requests, CODEOWNER approval, conversation
+   resolution, and the known required checks.
+7. The workflow cannot push to `main`, merge, force-push, delete branches, or
+   write to another repository.
+8. `REFRESH_APPROVER_LOGIN` is set to the exact approved GitHub login.
+
+Record the approver login, UTC timestamp, and trial evidence in
+`capabilities.json`. Do not replace an unknown capability with an assumption.
+
+## Audit findings
+
+The SSO-authorized keyring token completed a read-only audit on July 23, 2026.
+
+- Buildathon: Copilot Code Review is active; refresh labels and
+  `REFRESH_APPROVER_LOGIN` are configured. Active branch protection requires one
+  approval and conversation resolution. Disabled ruleset `19622585` is prepared
+  to require the Phase 0 checks, CODEOWNER approval, approval after the latest
+  push, conversation resolution, and to block deletion and force-push. A
+  separate human-only update template still requires administrator confirmation
+  because the user-bypass REST request returned HTTP 404.
+- Serverless Chat and MCP Agent remain external evidence sources only. No
+  workflow in Buildathon may write to them.
+
+The unavailable organization-owned GitHub App is no longer a blocker or planned
+dependency. Built-in-token event suppression and repository write permissions
+are the new technical gates.
+
+## Activation sequence
+
+1. Merge the Phase 0 pull request.
+2. Confirm or create the human-only merge ruleset in repository settings.
+3. Activate ruleset `19622585` and the human-only merge ruleset.
+4. Run read-only discovery trials.
+5. Run the bounded `GITHUB_TOKEN` issue, branch, PR, explicit-dispatch, and
+   Copilot-review spike.
+6. Enable issue-only reporting if issue writes pass.
+7. Enable Buildathon implementation only after every write/review gate passes.
+
+External CodeTour findings remain manual handoffs regardless of Buildathon
+capability results.

.github/agentic-refresh/github-token.json

@@ -0,0 +1,66 @@
+{
+  "version": 1,
+  "token": "GITHUB_TOKEN",
+  "scope": "current-repository-only",
+  "storedSecretRequired": false,
+  "personalTokenFallbackAllowed": false,
+  "crossRepositoryWritesAllowed": false,
+  "copilotInference": {
+    "permission": "copilot-requests: write",
+    "personalTokenFallbackAllowed": false
+  },
+  "permissionsByOperation": {
+    "discoveryReport": {
+      "contents": "read",
+      "issues": "write",
+      "copilot-requests": "write"
+    },
+    "implementation": {
+      "contents": "write",
+      "issues": "write",
+      "pull-requests": "write",
+      "copilot-requests": "write"
+    },
+    "validationDispatch": {
+      "actions": "write",
+      "contents": "read"
+    }
+  },
+  "constraints": {
+    "allowedRepository": "Azure-Samples/JavaScript-AI-Buildathon",
+    "allowedBranchPrefix": "refresh/",
+    "defaultBranchWritesAllowed": false,
+    "mergeAllowed": false,
+    "humanMergeRuleset": ".github/agentic-refresh/rulesets/human-merge.json"
+  },
+  "writeHandling": {
+    "agentGitHubTools": "read-only",
+    "consumer": "gh-aw-safe-outputs",
+    "allowedOperations": [
+      "createRefreshBranch",
+      "updateRefreshBranch",
+      "createPullRequest",
+      "updatePullRequest",
+      "createIssue",
+      "updateIssue",
+      "comment"
+    ],
+    "forbiddenOperations": [
+      "mergePullRequest",
+      "updateDefaultBranch",
+      "deleteBranch",
+      "forcePush",
+      "writeExternalRepository"
+    ]
+  },
+  "eventModel": {
+    "tokenGeneratedEventsTriggerWorkflows": false,
+    "explicitDispatchRequiredAfterPullRequestCreation": true,
+    "explicitDispatchRequiredAfterRefreshBranchUpdate": true,
+    "requiredCheckDispatchMustBeProvenBeforeWrites": true
+  },
+  "externalRepositories": {
+    "mode": "report-only",
+    "manualHandoffRequired": true
+  }
+}