Enrich material

Author: olivomarco

.squad/agents/zoe/history-archive-20260721-064206.md

@@ -86,9 +86,8 @@
     // Attribution
     const attr = document.getElementById('attribution');
     if (attr && c.source_repo) {
-      const sourceUrl = FP.githubSourceUrl(c.source_repo, c.source_path, c.source_ref);
-      const sourceLabel = FP.esc(c.source_repo + (c.source_path ? ` / ${c.source_path}` : ''));
-      attr.innerHTML = `Origin: <a href="${sourceUrl}" target="_blank" rel="noopener">${sourceLabel}</a> · ${FP.esc(c.license || 'MIT')} License`;
+      const sourceUrl = FP.githubSourceUrl(c.source_repo);
+      attr.innerHTML = `Origin: <a href="${sourceUrl}" target="_blank" rel="noopener">${FP.esc(c.source_repo)}</a>`;
     }
   }
 

docs/assets/js/challenge.js

@@ -84,7 +84,7 @@ <h1 id="heroHeading">Build Your<br><span class="accent">Agentic DevOps Practice<
           <p class="lede byo-lede">
             <strong>Bring your own.</strong> This runs on <em>your</em> tenant — work each
             activity against your own apps, repos, and data so the result keeps running in
-            production. The sample apps are only a fallback so no one is blocked.
+            production.
           </p>
           <div class="hero-actions">
             <a class="btn btn-primary" href="#outcomes">

docs/index.html

@@ -11,6 +11,6 @@ This is a concise review overlay. Apply the [Delivery Assurance Standard](../../
 
 ## Session-specific reviewer focus
 
-- Customer adoption outcome: the customer implementation owner makes "clone and code in 60 seconds" real — a committed, reproducible dev container, a prebuild for speed, and an...
-- Implementation risks to verify:
-- Delivery lead prompts: ask "what should every teammate get identically, and what's just your preference?" (→ devcontainer vs dotfiles), and "where did the time go on first...
+- Prebuild-aware setup belongs in `onCreateCommand` or `updateContentCommand`; do not accept dependency installation only in `postCreateCommand`.
+- Confirm the recorded trigger, regions, retained versions, and freshness behavior match the customer team's cost and dependency-freshness needs.
+- Inspect the successful prebuild workflow and a new **Prebuild ready** Codespace, then confirm both development rows are recorded in the governance register.

modules/ghec/challenges/ch03-codespaces-dev-containers/COACH.md

@@ -30,7 +30,7 @@
 This delivery engagement establishes:
 - Author a `devcontainer.json` that pins a base image, installs features, and runs setup commands.
 - Launch a Codespace from the UI and the CLI, and understand the create/stop/delete lifecycle.
-- Add lifecycle scripts (`postCreateCommand`, `postStartCommand`) and dev-container Features.
+- Use prebuild-aware lifecycle scripts (`onCreateCommand`, `postStartCommand`) and dev-container Features.
 - Forward and label ports, set port visibility, and run the seeded app inside the Codespace.
 - Apply personalization (dotfiles) vs project config, and understand the precedence.
 - Configure org-level Codespaces policy (machine-type limits, retention) and create a prebuild to cut start time.
@@ -72,11 +72,11 @@ What setup creates (all artifacts namespaced `ghec-ch03-*`, idempotent, prefix-g
 ### Part A — Author the dev container
 1. Inspect and extend `.devcontainer/devcontainer.json`. The fallback sample includes a minimal baseline with a pinned Node image, dependency install, and port 3000 forwarding. Keep the pinned base image suitable for the app (e.g., `mcr.microsoft.com/devcontainers/javascript-node:22`) and improve it.
 2. Add Features. Include at least two dev-container Features, e.g. `ghcr.io/devcontainers/features/github-cli:1` and `ghcr.io/devcontainers/features/node:1`. Understand Features vs baking tools into a custom Dockerfile.
-3. Add lifecycle commands. Set `postCreateCommand` to install dependencies (`npm ci`) and `postStartCommand` to print a ready message. Add a `customizations.vscode.extensions` list with at least one extension.
+3. Add lifecycle commands. Keep deterministic shared setup in `onCreateCommand` (`npm install` for the seeded app) and add `postStartCommand` to print a ready message. Prebuilds run `onCreateCommand`, but not `postCreateCommand`, so do not put the dependency install in `postCreateCommand`. Add a `customizations.vscode.extensions` list with at least one extension.
 
 ### Part B — Launch & run
 4. Open a Codespace from the repo's Code → Codespaces menu *and* from the CLI: `gh codespace create -R <org>/ghec-ch03-codespaces-dev-containers -m basicLinux32gb` (use the smallest available). List it with `gh codespace list`.
-5. Verify the environment inside the Codespace: `node -v` matches the pinned image, `gh --version` works (proves the Feature installed), and `npm ci` already ran (proves `postCreateCommand`).
+5. Verify the environment inside the Codespace: `node -v` matches the pinned image, `gh --version` works (proves the Feature installed), and `node_modules/express` exists (proves `onCreateCommand` installed dependencies).
 6. Run the app (`npm start`). Confirm it boots.
 
 ### Part C — Ports
@@ -88,18 +88,28 @@ What setup creates (all artifacts namespaced `ghec-ch03-*`, idempotent, prefix-g
 
 ### Part E — Org policy & prebuilds
 10. Set an org Codespaces policy. In Org settings → Codespaces, restrict the allowed machine types (e.g., disallow the largest) and set a retention period. Confirm the policy is visible via `gh api /orgs/<org>/codespaces` or the settings UI.
-11. Create a prebuild. Configure a Codespaces prebuild for the repo's default branch (Settings → Codespaces → Set up prebuild). Trigger it, wait for the prebuild Action run to succeed, then create a *new* Codespace and confirm it reports "prebuilt" and starts noticeably faster.
-12. Clean up running Codespaces with `gh codespace delete` to stop billing.
+11. Design the prebuild before creating it. In `docs/prebuild-decision.md`, record the repository branch and `devcontainer.json` you are targeting; the developer regions; the trigger you choose; the number of versions to retain; the owner for failed-prebuild notifications; and the rationale. Select the settings for this customer:
+   - **Every push** keeps dependencies current but consumes more Actions minutes.
+   - **On configuration change** reduces Actions usage but may leave dependencies stale until a developer updates them.
+   - **Scheduled** suits a deliberate refresh cadence, with the same freshness trade-off.
+   - Limit regions to where the delivery team works. Each enabled region and retained version consumes prebuild storage.
+   - Retain only the number of versions needed for rollback or investigation (1–5). Decide whether developers should be blocked from a fallback when the latest prebuild is running or failed.
+12. Create the prebuild from the recorded decision (Settings → Codespaces → Set up prebuild). Select the branch and configuration file, trigger, regions, retained versions, failure-notification owner, and advanced freshness behavior. Wait for the GitHub Actions prebuild workflow to succeed.
+13. Validate the result. Create a *new* Codespace for the configured branch and configuration. Confirm the machine picker shows **Prebuild ready**, `node_modules/express` is already present, and the repository settings show the successful configuration and its next update trigger. Record the workflow URL or run ID in `docs/prebuild-decision.md`.
+14. Clean up running Codespaces with `gh codespace delete` to stop billing.
+15. Update the governance register initialized in Ch06. Add two `development` rows: **dev-container standardization** (effective level: `repo`; evidence: `.devcontainer/devcontainer.json` and a successful Codespace) and **prebuild strategy** (effective level: `org`/`repo`; evidence: `docs/prebuild-decision.md`, the prebuild workflow run, and the policy setting). Record the platform owner, implementation path (`approved pilot` or `inspect-and-propose`), review cadence, and next decision.
 
 ## Validation / Definition of Done
 You are done when ALL of the following are true:
-- [ ] `.devcontainer/devcontainer.json` exists, pins a base image, includes ≥2 Features, and sets `postCreateCommand` + `postStartCommand`.
+- [ ] `.devcontainer/devcontainer.json` exists, pins a base image, includes ≥2 Features, and sets `onCreateCommand` + `postStartCommand`.
 - [ ] A Codespace was launched from both the UI and the CLI (`gh codespace list` showed it).
 - [ ] Inside the Codespace, the pinned Node version, the gh CLI Feature, and the post-create install are all verifiable.
 - [ ] The app runs and its port is forwarded + labeled, with `forwardPorts`/`portsAttributes` committed to config.
 - [ ] `docs/devcontainer-notes.md` explains dotfiles vs devcontainer.json precedence.
 - [ ] An org Codespaces policy restricts machine types and sets retention.
-- [ ] A prebuild is configured and a new Codespace reports prebuilt.
+- [ ] `docs/prebuild-decision.md` records the branch/configuration, trigger, regions, retained versions, failure-notification owner, freshness behavior, and customer-specific cost/freshness rationale.
+- [ ] A prebuild is configured; its GitHub Actions workflow succeeds; and a new Codespace reports **Prebuild ready** with dependencies already installed.
+- [ ] The governance register contains development rows for the dev-container standard and prebuild strategy, with effective level, evidence, owner, implementation path, and next decision.
 - [ ] All your Codespaces are stopped/deleted at the end.
 - [ ] Real-outcome check — if you brought your own repo, it now has a Codespace/devcontainer path that reduces real onboarding friction; if you used the sample, you can name the repo whose setup you will standardize next.
 - [ ] Adoption handover — name the repository owner, onboarding bottleneck, approved dev-container change, and next rollout action.
@@ -118,5 +128,6 @@ You are done when ALL of the following are true:
 - Forwarding ports in your codespace — https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace
 - Managing Codespaces for your organization — https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-repository-access-for-your-organizations-codespaces
 - Configuring prebuilds — https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds
+- About Codespaces prebuilds — https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds
 - Personalizing Codespaces with dotfiles — https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account
 - `gh codespace` CLI manual — https://cli.github.com/manual/gh_codespace

modules/ghec/challenges/ch03-codespaces-dev-containers/README.md

@@ -11,16 +11,18 @@ prerequisite_capabilities:
 - git installed
 - jq installed
 - Repository provisioned via activity setup script
-description: "Implement an authorized customer reproducible development environment with `devcontainer.json`, Codespaces, port forwarding, organization-level Codespaces policy, and prebuilds. Preserve the configuration, operating owner, cost controls, and rollout decision."
+description: "Implement an authorized customer reproducible development environment with `devcontainer.json`, Codespaces, port forwarding, organization-level Codespaces policy, and tuned prebuilds. Preserve the configuration, prebuild operating decision, cost controls, and rollout decision."
 success_criteria:
-- '`.devcontainer/devcontainer.json` exists, **pins a base image**, includes **≥2 Features**, and sets `postCreateCommand` + `postStartCommand`.'
+- '`.devcontainer/devcontainer.json` exists, **pins a base image**, includes **≥2 Features**, and sets `onCreateCommand` + `postStartCommand`.'
 - A Codespace was launched from **both** the UI and the CLI (`gh codespace list` showed it).
 - Inside the Codespace, the pinned **Node version**, the **gh CLI Feature**, and the **post-create install** are all verifiable.
 - The app **runs** and its port is **forwarded + labeled**, with `forwardPorts`/`portsAttributes` committed to config.
 - '`docs/devcontainer-notes.md` explains **dotfiles vs devcontainer.json** precedence.'
 - An **org Codespaces policy** restricts machine types and sets retention.
-- A **prebuild** is configured and a new Codespace reports **prebuilt**.
+- '`docs/prebuild-decision.md` records the branch/configuration, trigger, regions, retained versions, failure-notification owner, freshness behavior, and customer-specific cost/freshness rationale.'
+- A **prebuild** is configured, its workflow succeeds, and a new Codespace reports **Prebuild ready** with dependencies already installed.
 - All your Codespaces are **stopped/deleted** at the end.
+- '**Governance register updated:** Added rows for development (dev-container standardization and prebuild strategy) with links to `devcontainer.json`, `docs/prebuild-decision.md`, and org Codespaces policy.'
 - Customer-owned implementation evidence identifies the authorized scope, accountable owner, relevant risk controls, handover artefact, and next adoption, cutover, or rollout decision.
 tags:
 - codespaces
@@ -44,6 +46,7 @@ references:
 - https://docs.github.com/en/codespaces/overview
 - https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace
 - https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds
+- https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds
 - https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-repository-access-for-your-organizations-codespaces
 - https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account
 - https://containers.dev/implementors/json_reference/

modules/ghec/challenges/ch03-codespaces-dev-containers/meta.yml

@@ -11,6 +11,7 @@ This is a concise review overlay. Apply the [Delivery Assurance Standard](../../
 
 ## Session-specific reviewer focus
 
-- Customer adoption outcome: the customer implementation owner builds a real CI pipeline that runs across a matrix, caches deps, publishes artifacts, and — the key outcome —...
-- Implementation risks to verify:
-- Delivery lead prompts: ask "what exact string does the merge gate look for?" (→ check name), and "what makes the second run faster than the first?" (→ cache hit).
+- Customer adoption outcome: the customer implementation owner builds a real CI pipeline that runs across a matrix, caches deps, publishes artifacts, and sets default token permissions (`read-only` for workflows).
+- **Governance register row:** Confirm one register row added for Actions workflow default permissions (set to `read` at org level so workflows cannot write code/secrets by default). Row uses `approved pilot` status with link to org Settings > Actions > Workflow permissions.
+- Implementation risks to verify: ask "what exact string does the merge gate look for?" (→ check name) and "what makes the second run faster than the first?" (→ cache hit + cache scope).
+- Delivery lead prompts: ask "what's the risk if a workflow can write a token back to the repo?" (→ supply-chain attack) and "how long should Actions cache survive?" (→ org policy).

modules/ghec/challenges/ch04-actions-ci-fundamentals/COACH.md

@@ -94,6 +94,18 @@ What setup creates (all artifacts namespaced `ghec-ch04-*`, idempotent, prefix-g
 10. Create an environment named `staging` with a required reviewer protection rule. Add an environment variable and a secret; have the `package` job reference the `staging` environment and echo the variable (never the secret).
 11. Make CI required. In branch protection / a ruleset on `main`, mark the `build-test` status check as required. Then flip the seeded failing test on, push, and confirm the PR is blocked from merging. Flip it back to green and confirm the block clears.
 
+### Part G — Governance register: Actions policy & CI posture
+
+Capture the governance decisions that make CI repeatable and safe across the org. This activity is 4 steps: inspect enterprise/org policy override, make one approved pilot decision on the allowed-actions boundary, prove CI compatibility, and record the decision.
+
+1. **Inspect effective Actions policy & dependencies.** Read the enterprise and org Actions policy by checking Org Settings → Actions → General → Allowed actions and reusable workflows. Record whether the setting reads "All actions and reusable workflows" (permissive) or "Allow specified actions and reusable workflows" (restricted). List the Actions and reusable-workflow dependencies in `.github/workflows/ci.yml` (e.g., `actions/setup-node`, `actions/upload-artifact`, `actions/cache`, any custom actions). Record which ones are first-party (owned by GitHub) vs third-party.
+
+2. **Make ONE approved policy pilot.** Choose and execute exactly one: **(a) Approved pilot:** If your org policy will restrict Actions, document the approved allowlist in the `Allowed actions` field. Include every dependency the workflow needs, for example `actions/checkout`, `actions/setup-*`, `actions/upload-*`, `actions/cache`, and any custom actions you identified. Record the effective level (`org`), implementation path (`approved pilot`), and customer-owned evidence (a screenshot or API dump showing the restricted setting + its value). **OR (b) Inspect-and-propose fallback:** If you lack authority to change the policy, record the current org policy, the identified Actions dependencies, and a one-paragraph rationale for a proposed allowlist in `docs/ACTIONS-POLICY.md`, with the effective level (`org`), implementation path (`inspect-and-propose`), and customer owner name.
+
+3. **Prove CI compatibility & capture token posture.** Run the workflow twice (push a branch and open a PR). Confirm both runs complete successfully and all steps execute (setup, lint, test, build, cache, artifacts all pass). Document the `GITHUB_TOKEN` permission scope used in the workflow (check the `permissions:` block in `.github/workflows/ci.yml`) and whether fork PRs have the same token scope. Record artifact retention (default or custom) and whether logs are retained or deleted.
+
+4. **Write the governance-register decision record.** Open the governance register you initialized in Ch06 (or create one now from `modules/ghec/resources/GOVERNANCE-SETTINGS-REGISTER-TEMPLATE.md`). Add rows for: (i) **Actions policy / allowed-actions boundary** (domain: `workflow`, effective level: `org`, implementation path from step 2, customer owner name, evidence: policy screenshot + `docs/ACTIONS-POLICY.md` or allowlist export); (ii) **Workflow token permissions** (domain: `workflow`, effective level: `org`, implementation path: `approved pilot`, desired value: `read` for standard workflows, evidence: workflow run with read-only token confirmed in logs); (iii) **Artifact/log retention** (domain: `workflow`, effective level: `org`/`repo`, implementation path: `approved pilot` if custom, evidence: retention setting + test artifact download evidence). Leave Next Decision blank for the next review.
+
 ## Validation / Definition of Done
 You are done when ALL of the following are true:
 - [ ] `.github/workflows/ci.yml` triggers on push and pull_request and runs lint + test + build as distinct steps.
@@ -103,6 +115,7 @@ You are done when ALL of the following are true:
 - [ ] A second job uses `needs` and a conditional so it only runs on `main`.
 - [ ] An environment `staging` exists with a protection rule and a variable + secret wired into a job.
 - [ ] The `build-test` check is required on `main`; a red run blocks merge, a green run unblocks it.
+- [ ] The governance register records the effective Actions/reusable-workflow policy, workflow-token and fork-PR posture, and artifact/log retention decision, with compatibility evidence from the CI pilot.
 - [ ] Real-outcome check — if you brought your own repo, CI now runs against a real build or test path; if you used the sample, you can name the workflow you will automate next.
 - [ ] Adoption handover — name the customer test or build process, workflow owner, required gate, and next approved rollout action.