Add APM (Agent Package Manager) coverage: dependencies in Ch11, supply-chain governance in Ch13

Weave APM into Ch11 (imports -> shared/apm.md packages, apm.lock pinning) and Ch13 (apm-policy.yml allowlists, SHA pinning + Unicode scanning, isolated mode, air-gapped proxy). Update research notes, toc.yml feature lists, outline.md, playbook-brief.md. Regenerate site (llms-full.txt + reading times). Cites gh-aw dependencies reference and GitHub Well-Architected governing-agentic-workflows.

Author: webmaxru

content/chapters/governance-and-finops.html

@@ -4,8 +4,8 @@
      with inner HTML; keep the data-slot ids unchanged (they map 1:1 to page slots). -->
 
 <section data-slot="objective" data-title="Objective">
-  <p>By the end of this chapter you can <strong>cap, meter, and gate</strong> agentic spend &mdash; with <code>max-ai-credits</code> per-workflow budgets and org-wide defaults &mdash; and set the policy that keeps a fleet affordable and compliant as it grows.</p>
-  <p>Everything targets <strong>gh aw v0.81.6</strong>. We put a hard budget on the Repo Assistant and show how an org enforces the same limits across every repo at once.</p>
+  <p>By the end of this chapter you can <strong>cap, meter, and gate</strong> agentic spend &mdash; with <code>max-ai-credits</code> per-workflow budgets and org-wide defaults &mdash; and set the policy that keeps a fleet affordable and compliant as it grows. That policy surface extends past cost to the agent's <em>supply chain</em>: which skills and prompts your workflows are even allowed to consume.</p>
+  <p>Everything targets <strong>gh aw v0.81.6</strong>. We put a hard budget on the Repo Assistant and show how an org enforces the same limits &mdash; and the same approved dependency list &mdash; across every repo at once.</p>
 </section>
 
 <section data-slot="concept-agentic-work-has-a-budget-and-a-policy-surface" data-title="Concept: agentic work has a budget and a policy surface">
@@ -47,6 +47,28 @@ <h3>Org-wide defaults and policy</h3>
     <p class="callout-title">Builder detail: the recommended rollout</p>
     <p>The docs prescribe a layered rollout: <em>enterprise baseline &rarr; org where needed &rarr; repo exceptions &rarr; rare, explicit frontmatter overrides.</em> Preview any change with <code>gh aw env update &hellip; --dry-run</code> before applying. Most repos stay aligned to the baseline; exceptions are deliberate and visible.</p>
   </aside>
+
+  <h3>Governing the agent supply chain (APM)</h3>
+  <p>Budgets and policy variables govern <em>spend</em> and <em>capabilities</em>. A third surface is the <em>dependency</em> supply chain from <a class="xref" href="reuse-and-memory.html">Chapter 11</a>: the skills, prompts, and plugins an agent consumes are executable context, so an unreviewed one is an injection vector &mdash; exactly the <a class="xref" href="defense-in-depth.html">Chapter 7</a> threat model. The <strong>Agent Package Manager (APM)</strong> &ldquo;treats agent skills as packages with the same governance primitives that enterprises require for code dependencies&rdquo; (<a href="https://learn.github.com/well-architected/governance/recommendations/governing-agentic-workflows">Governing agentic workflows</a>).</p>
+  <p>Three controls turn that supply chain into a governed surface:</p>
+  <ul>
+    <li><strong>Pinning &amp; scanning.</strong> Every package is pinned to an exact commit SHA in an <code>apm.lock.yaml</code> so &ldquo;there is no drift between what was reviewed and what actually runs,&rdquo; and install-time scanning flags &ldquo;hidden Unicode threats like homoglyphs, bidirectional override characters, and zero-width joiners&rdquo; that could smuggle invisible instructions into a prompt (<a href="https://learn.github.com/well-architected/governance/recommendations/governing-agentic-workflows">Governing agentic workflows</a>).</li>
+    <li><strong>Org-level allowlists.</strong> An <code>apm-policy.yml</code> in the org's <code>.github</code> repository controls which packages any repo may consume. Inheritance is <em>tighten-only</em> across enterprise &rarr; org &rarr; repo &mdash; children &ldquo;can narrow allowlists, add deny entries, and escalate enforcement, but&hellip; cannot relax constraints set by a parent&rdquo; &mdash; the same percolation model as your cost defaults, applied to dependencies.</li>
+    <li><strong>Isolation.</strong> Importing a skill with <code>isolated: true</code> means &ldquo;the agent sees only the skill's packaged instructions,&rdquo; so a compromised repo-level <code>AGENTS.md</code> or <code>copilot-instructions.md</code> cannot silently override a security skill's rules (<a href="https://learn.github.com/well-architected/governance/recommendations/governing-agentic-workflows">Governing agentic workflows</a>).</li>
+  </ul>
+  <figure class="code">
+    <figcaption>Illustrative: an org-wide dependency allowlist in <code>.github/apm-policy.yml</code></figcaption>
+    <pre><code class="language-yaml">name: "Org agent governance"
+enforcement: block
+dependencies:
+  allow:
+    - "org/approved-security-skills/*"
+    - "org/approved-review-skills/*"
+  deny:
+    - "*"                       # deny everything not explicitly allowed
+  require_pinned_constraint: true</code></pre>
+  </figure>
+  <p>Together &mdash; lockfile + org policy + isolation &mdash; these give a platform team a complete answer to the compliance question &ldquo;show me exactly what instructions the agent followed, at what version.&rdquo; Air-gapped shops can go further and route all downloads through a corporate scanning proxy (<code>PROXY_REGISTRY_ONLY=1</code>) so nothing is fetched directly from GitHub (<a href="https://learn.github.com/well-architected/governance/recommendations/governing-agentic-workflows">Governing agentic workflows</a>).</p>
 </section>
 
 <section data-slot="when-to-cap-meter-and-gate-cost-and-risk-trade-offs" data-title="When to cap, meter, and gate (cost and risk trade-offs)">
@@ -60,6 +82,7 @@ <h3>Org-wide defaults and policy</h3>
       <tr><td>an occasional deep task (refactor)</td><td>a higher per-run budget, no aggressive daily cap</td></tr>
       <tr><td>a whole org</td><td>generous enterprise defaults, tightened per-org/repo</td></tr>
       <tr><td>a capability you want to forbid</td><td>a <code>GH_AW_POLICY_*</code> gate, not per-workflow edits</td></tr>
+      <tr><td>the skills/prompts agents may use</td><td>an <code>apm-policy.yml</code> allowlist + committed, pinned <code>apm.lock</code></td></tr>
     </tbody>
   </table>
 
@@ -69,6 +92,7 @@ <h3>When <em>not</em> to</h3>
     <li><strong>Don't set org defaults so tight that every repo overrides them.</strong> If exceptions become the norm, the baseline is wrong. The goal is most repos aligned, few exceptions.</li>
     <li><strong>Don't rely on budgets for security.</strong> A budget limits <em>spend</em>, not <em>blast radius</em> &mdash; that's still safe outputs, the firewall, and policy gates (Chapters 6&ndash;8). Cost controls and security controls are complementary.</li>
     <li><strong>Don't govern by editing workflows.</strong> At scale, prefer <code>gh aw env</code> defaults and <code>GH_AW_POLICY_*</code> gates &mdash; central, reviewable, and applied without recompiling every repo.</li>
+    <li><strong>Don't let agents pull skills you haven't approved.</strong> An unpinned, unscanned skill package is an ungoverned instruction source; set an <code>apm-policy.yml</code> allowlist and require pinned constraints before you widen a fleet, not after.</li>
   </ul>
 </section>
 
@@ -126,6 +150,7 @@ <h3>When <em>not</em> to</h3>
     <li>Agentic work has a <strong>variable cost</strong> and, at scale, a <strong>policy surface</strong> &mdash; FinOps and governance now apply to your agents.</li>
     <li>Per-workflow: <code>max-ai-credits</code> (default 1000, steering at 80/90/95/99%), <code>max-daily-ai-credits</code> (fail-safe daily cap), <code>timeout-minutes</code>, and <code>stop-after</code>.</li>
     <li>Org-wide: <code>gh aw env</code> sets <code>GH_AW_DEFAULT_*</code> defaults that <strong>percolate</strong> (frontmatter &rarr; repo &rarr; org &rarr; enterprise), and <code>GH_AW_POLICY_*</code> variables <strong>gate capabilities</strong> without recompiling.</li>
+    <li>Supply chain: <strong>APM</strong> governs <em>which</em> skills a fleet may use &mdash; SHA-pinned <code>apm.lock.yaml</code>, install-time Unicode scanning, a tighten-only <code>apm-policy.yml</code> allowlist, and <code>isolated: true</code> imports that repo config can't override.</li>
     <li>Tune budgets to the work, roll out defaults in layers, and remember budgets limit <em>spend</em>, not <em>blast radius</em>.</li>
   </ul>
   <p><strong>What's next.</strong> You can now build, secure, operate, and govern agentic workflows. The final chapter zooms all the way out: <a class="xref" href="fleets-and-adoption.html">Chapter 14: Fleets &amp; Adoption</a> takes the Repo Assistant from one repo to a multi-repo fleet and lays out the enterprise adoption playbook.</p>

content/chapters/reuse-and-memory.html

@@ -33,6 +33,21 @@ <h3>Imports and shared components</h3>
   </figure>
   <p>Paths resolve three ways: <strong>relative</strong> to the workflow, <strong>repo-root</strong> (<code>.github/&hellip;</code>), or <strong>cross-repo</strong> as <code>owner/repo/path@ref</code> &mdash; and cross-repo imports are &ldquo;pinned to a semantic tag, branch, or commit SHA&rdquo; and cached for offline compiles (<a href="https://github.github.com/gh-aw/reference/imports/">Imports</a>). Fields merge sensibly: tool allowlists concatenate and dedupe; each safe-output type is defined once, with the main workflow winning on conflict.</p>
 
+  <h3>Packaging dependencies: the Agent Package Manager (APM)</h3>
+  <p>Imports compose files you write. But agents increasingly depend on <em>published</em> primitives &mdash; skills, prompts, instructions, sub-agents, hooks, and plugins &mdash; that live in other repositories and evolve on their own cadence. The <strong>Agent Package Manager (APM)</strong> &ldquo;manages AI agent primitives&hellip; Packages can depend on other packages and APM resolves the full dependency tree&rdquo; (<a href="https://github.github.com/gh-aw/reference/dependencies/">APM Dependencies</a>). It is the same DRY instinct as a shared component, but for the agent's <em>context</em> rather than its config &mdash; a real package manager for agent intelligence.</p>
+  <p>APM plugs into gh-aw through exactly the mechanism you just learned: you import a shared file, <code>shared/apm.md</code>, and pass it the packages you want. That import &ldquo;adds a dedicated <code>apm</code> job&rdquo; that resolves and packs the packages into a bundle at build time, which the agent job unpacks &ldquo;for deterministic startup&rdquo; (<a href="https://github.github.com/gh-aw/reference/dependencies/">APM Dependencies</a>).</p>
+  <figure class="code">
+    <figcaption>Illustrative: depend on published skills via the <code>shared/apm.md</code> import</figcaption>
+    <pre><code class="language-yaml">imports:
+  - uses: shared/apm.md            # vendored from microsoft/apm via `gh aw add`
+    with:
+      packages:
+        - microsoft/apm-sample-package                       # a full package
+        - github/awesome-copilot/skills/review-and-refactor  # one primitive
+        - anthropics/skills/skills/frontend-design#v2.0      # pinned to a tag</code></pre>
+  </figure>
+  <p>Each entry is a package reference in one of three shapes: <code>owner/repo</code> (a full package), <code>owner/repo/path</code> (a single primitive such as one skill), or <code>owner/repo#ref</code> (pinned to a tag, branch, or SHA) (<a href="https://github.github.com/gh-aw/reference/dependencies/">APM Dependencies</a>). Reproducibility is the point: an <code>apm.lock</code> file &ldquo;pin[s] every package to an exact commit SHA, so the same versions are installed on every run,&rdquo; and those lock diffs &ldquo;appear in pull requests and are reviewable before merge&rdquo; &mdash; an audit trail for exactly which agent context is in use. That reviewable, pinnable supply chain is what makes APM <em>governable</em> at org scale, which we return to in <a class="xref" href="governance-and-finops.html">Chapter 13</a>.</p>
+
   <h3>Repo memory vs. cache memory</h3>
   <p>Persistence comes in two flavors, and choosing correctly matters. <strong>Repo memory</strong> gives &ldquo;persistent file storage via Git branches with unlimited retention&rdquo; &mdash; enable it with <code>tools: repo-memory: true</code> and the compiler auto-configures a <code>memory/default</code> branch that files &ldquo;auto-commit/push after workflow completion&rdquo; (<a href="https://github.github.com/gh-aw/reference/repo-memory/">Repo Memory</a>). <strong>Cache memory</strong> uses the GitHub Actions cache instead &mdash; fast, but 7-day retention and no version control.</p>
   <table>
@@ -68,6 +83,7 @@ <h3>Repo memory vs. cache memory</h3>
   <h3>When <em>not</em> to</h3>
   <ul>
     <li><strong>Don't track a moving branch for cross-repo imports.</strong> Pin to a tag or SHA (<code>@v2.1.0</code>), not <code>@main</code> &mdash; an unpinned import is a supply-chain risk, the same lesson as unpinned engine versions in <a class="xref" href="engines.html">Chapter 5</a>.</li>
+    <li><strong>Don't consume APM packages unpinned or unreviewed.</strong> A skill is executable context: commit the <code>apm.lock</code>, review its diffs, and pin references. Skills you don't control are exactly where the <a class="xref" href="defense-in-depth.html">Chapter 7</a> threat model applies &mdash; govern them (Chapter 13), don't trust them by default.</li>
     <li><strong>Don't put secrets in memory.</strong> Repo memory follows repository permissions and lives in a branch; &ldquo;don't store sensitive data in repo memory.&rdquo; Keep secrets in Actions secrets, always.</li>
     <li><strong>Don't reach for repo memory when cache memory fits.</strong> Session-only scratch state doesn't need an unlimited, version-controlled branch &mdash; use the faster 7-day cache.</li>
     <li><strong>Don't over-abstract.</strong> A shared component with fifteen parameters is harder to reason about than two honest copies. Share the stable core; let the edges vary.</li>
@@ -127,6 +143,7 @@ <h3>When <em>not</em> to</h3>
   <ul>
     <li>As you scale to many repos, factor common intent into <strong>shared components</strong> &mdash; files without <code>on:</code> that others <code>import</code>.</li>
     <li>Imports resolve <strong>relative</strong>, <strong>repo-root</strong>, or <strong>cross-repo</strong> (<code>owner/repo/path@ref</code>, pinned); fields merge, and <code>import-schema</code> allows typed parameters.</li>
+    <li>The <strong>Agent Package Manager (APM)</strong> rides the same import mechanism (<code>shared/apm.md</code> + <code>packages:</code>) to depend on published skills/prompts/plugins, pinned to exact SHAs in an <code>apm.lock</code> for reproducible, reviewable builds.</li>
     <li><strong>Repo memory</strong> (Git branches, unlimited, versioned) vs. <strong>cache memory</strong> (Actions cache, 7-day, fast) give the agent persistence across runs.</li>
     <li>Follow the <strong>rule of three</strong>, <strong>pin</strong> cross-repo imports, and never store secrets in memory.</li>
   </ul>

content/outline.md

@@ -30,9 +30,9 @@ matters, governance, cost, rollout) through margin callouts.
 | 8 | II | Builder | Tools & MCP: Real Capabilities, Governed | Add governed capabilities via `tools:` and MCP servers | `tools:`; MCP servers; MCP gateway; built-in tools; tool permissions | 7 |
 | 9 | II | Both | Continuous Triage & Docs: Reading the Room | Ship the Triage and Docs patterns as mini-products | Continuous Triage; Continuous Docs; scheduled+event triggers; agentics samples | 6, 8 |
 | 10 | II | Both | Continuous Review, Testing & CI-Doctor | Close the quality loop with review/test/heal patterns | Review; Testing; CI-Doctor; Refactoring; `pull_request` triggers | 9 |
-| 11 | III | Builder | Reuse & Memory: Shared Components and Repo Knowledge | Factor shared intent via `imports:` and add persistent memory | `imports:`; shared components; memory/persistence; AGENTS.md | 10 |
+| 11 | III | Builder | Reuse & Memory: Shared Components and Repo Knowledge | Factor shared intent via `imports:` and add persistent memory | `imports:`; shared components; APM dependencies (`shared/apm.md`); memory/persistence; AGENTS.md | 10 |
 | 12 | III | Both | Trust & Operate: Observability and Debugging | Inspect, debug, and audit runs to trust the fleet | `gh aw logs`; `gh aw audit`; OpenTelemetry; run summaries; HITL review | 11 |
-| 13 | III | Leader | Governance & FinOps: Policy and Cost at Scale | Cap, meter, and gate agentic spend and set org policy | `max-ai-credits`; AI Credits; token efficiency; governance/policy | 12 |
+| 13 | III | Leader | Governance & FinOps: Policy and Cost at Scale | Cap, meter, and gate agentic spend and set org policy | `max-ai-credits`; AI Credits; token efficiency; governance/policy; APM supply-chain governance (`apm-policy.yml`) | 12 |
 | 14 | III | Leader | Fleets & Adoption: From One Repo to the Org | Scale into a governed multi-repo fleet with a rollout playbook | multi-repo fleets; dispatcher pattern; cross-repo composition; adoption playbook | 13 |
 
 **Parts (maturity arc):** **Part I — The Individual** (chs 1–5) · **Part II — The Team** (chs 6–10) ·

content/playbook-brief.md

@@ -96,10 +96,11 @@ Motivation comes from real adopters, not hypotheticals. Chapters open or close w
 - **The security model:** permissions, network firewall, Strict Mode, and sandbox isolation.
 - **Tools & MCP (`tools:`):** giving workflows real, governed capabilities.
 - **The Continuous-X pattern library:** triage, docs, review, CI-doctor, testing, refactoring.
-- **Reuse & memory:** shared components (`imports:`) and repo memory.
+- **Reuse & memory:** shared components (`imports:`), agent dependencies via APM (`shared/apm.md`), and repo memory.
 - **Trust & operate:** reviewing, debugging (`gh aw logs` / `gh aw audit`), human-in-the-loop.
 - **Scale for leaders:** governance and policy, cost & FinOps (AI Credits, token efficiency),
-  multi-repo fleets, and an enterprise adoption playbook.
+  agent-dependency governance (APM: pinning, allowlists, isolation), multi-repo fleets, and an
+  enterprise adoption playbook.
 
 ## Out of scope
 - Building or teaching Microsoft Agent Framework, LangChain, or other agent SDKs.

content/research/ch11-features.md

@@ -18,6 +18,14 @@
 - Merge: tools deep-merge (allowed arrays concat+dedupe); safe-outputs each type once (main wins);
   network allowed union; permissions validation-only (main must declare imported perms).
 - `inlined-imports: true` embeds imports into lock (self-contained; for cross-org workflow_call / rulesets).
+- **APM (Agent Package Manager)** rides the import mechanism: import `shared/apm.md` (vendored from
+  `microsoft/apm` via `gh aw add microsoft/apm/.github/workflows/shared/apm.md --dir shared`) and pass
+  `with: packages: [...]`. Adds a dedicated `apm` job that packs packages into a bundle artifact; agent
+  job unpacks for deterministic startup. Manages skills/prompts/instructions/agents/hooks/plugins;
+  resolves full dependency tree. Package ref formats: `owner/repo` | `owner/repo/path` | `owner/repo#ref`.
+  `apm.lock` pins every package to an exact commit SHA (reproducible; lock diffs reviewable in PRs).
+  Token fallback GH_AW_PLUGINS_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN. Governance detail → ch13.
+  Source: reference/dependencies/ (https://github.github.com/gh-aw/reference/dependencies/).
 - **repo-memory:** `tools: repo-memory: true` → Git-branch storage, UNLIMITED retention, versioned,
   `/tmp/gh-aw/repo-memory-default/`, auto-commit/push (GraphQL signed commits). vs **cache-memory:**
   Actions cache, 7-day, fast, not versioned. Comparison table verified.