📖 docs: mirror copilot-permissions-comparison from hive

changelog.d/added-501-copilot-permissions-comparison.md

@@ -0,0 +1,3 @@
+- The Hive trust levels vs Copilot assisted permissions page is now mirrored at
+  `/docs/hive/copilot-permissions-comparison` and listed in the Security
+  sidebar (hivecommons/docs#501).

docs/content/hive/copilot-permissions-comparison.md

@@ -0,0 +1,134 @@
+> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/copilot-permissions-comparison.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# Hive trust levels vs GitHub Copilot assisted permissions
+
+Last reviewed: 2026-10-27
+
+GitHub made Copilot "assisted permissions" generally available on 2026-10-26.
+This page says what that feature is, what Hive does in the same space, and
+where each does something the other does not. It is a comparison, not a
+ranking. The two tools answer different questions.
+
+## What Copilot assisted permissions is
+
+Source: the GitHub changelog entry of 2026-10-26,
+<https://github.blog/changelog/2026-10-26-github-copilot-assisted-permissions-generally-available>,
+and the docs page it links,
+<https://docs.github.com/copilot/concepts/customizations/allowing-safe-commands>.
+
+- It is a permission mode for one Copilot session in Copilot CLI, the Copilot
+  app, and VS Code. The three modes are manual approval, assisted, and
+  unconditional approval (`--allow-all` / `--yolo`).
+- When Copilot wants to run a shell command, touch a file path, or open a URL,
+  a second language model looks at the request. If that model is confident the
+  action is safe, the action runs with no prompt. If not, the user is asked.
+- In non-interactive runs (`copilot -p ... --assisted-approval`, or
+  `COPILOT_ASSISTED_APPROVAL=true` in CI), there is nobody to ask, so anything
+  the review model will not clear is denied and the reason is handed back to
+  Copilot so it can try another route.
+- Existing allow and deny rules run first. Enterprise deny rules still apply.
+  Enterprise admins can block the unconditional mode while leaving assisted
+  on, disable assisted on its own, and set the default mode for new sessions.
+- GitHub's own docs say it "is not a substitute for sandboxing or access
+  restrictions" and that the review model "can make mistakes and approve
+  dangerous or unintended actions".
+
+In short: it decides, per action, inside one developer's session, whether to
+show a prompt. It does not know about pull requests, merges, or repositories.
+
+## What Hive does
+
+Hive runs fleets of agents against repositories without a person at the
+keyboard. Its controls are about what reaches GitHub, not about prompts.
+
+- **Trust levels (ACMM L1-L6).** The level decides which agents run and in
+  which policy mode. Advisory agents write nothing to GitHub. Measured agents
+  may open issues. Hold-gated agents may open PRs, and every PR carries a
+  `hold` label a human must remove. Full agents may merge on green CI. L1 and
+  L2 are advisory, L3 and L4 add issues and hold-gated PRs, L5 opens PRs under
+  `hold`, and only L6 merges. See [ACMM policy matrix](/docs/hive/acmm-policy-matrix).
+- **Lanes.** Each piece of work is assigned to a lane, the agent that owns it
+  (scanner, reviewer, ci-maintainer, and so on). GitHub writes are allowlisted
+  per lane in `write_surface.allowlist`, and a lane can be listed in
+  `write_surface.enforce`. See [GitHub write surface](https://github.com/hivecommons/hive/blob/v5/src/docs/github-write-surface.md).
+- **The policy proxy.** Every agent's GitHub traffic passes through a
+  man-in-the-middle proxy (`pkg/proxy`). For an enforced lane it refuses every
+  REST `POST`, `PUT`, `PATCH`, `DELETE`, every GraphQL mutation, and `git push`,
+  returns `403`, and writes an `agent_write_refused` audit entry. Reads and
+  the hive's own relays keep working. The proxy also applies repo pause, agent
+  repo scope, the auto-merge policy, and the ACMM mode gate. The refusals are
+  counted. Read on 2026-10-27 from `GET /api/evidence/write-counters` on the
+  three hosted hives (hivecommons, hivecommons, projectbluefin), since the
+  counter started on 2026-10-12: 538 direct agent write attempts, 123 refused,
+  all with reason `mode_denied`. Hub admins see the same counters pooled in
+  `GET /api/hub/evidence` (`write_counters[]` with `block_rate`).
+- **Review gates.** `bin/merge-gate.sh` is deterministic: required CI green,
+  not a draft, no `hold`, and an approved review for community PRs. The
+  reviewer swarm adds verdicts after the change; `review.require_approval`
+  makes a same-head approval required at L6. See [review swarm](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md)
+  and [running at level 6](/docs/hive/running-at-level-6).
+- **Hold and approval.** Below L6 every agent PR gets `hold`; a human removes
+  it. `needs-human` parks a PR for a person. At L6 a `reject` or
+  `changes_requested` verdict still needs a fix or a human merge. See
+  [labels and control signals](/docs/hive/labels-and-control-signals).
+- **Shadow gates.** `governor.review_gate.mode: shadow` (the default) and
+  `intent.shadow` evaluate a gate and record what it would have held, and never
+  block. The record is in each evidence bundle under `shadow`. The study that
+  would turn those records into an accuracy figure is planned and not yet
+  running ([ablation plan](https://github.com/hivecommons/hive/blob/v5/src/docs/research/ablation-plan-2026-10.md)). Enforcement from
+  a shadow result is a config switch, not a separate feature.
+- **Evidence.** Every mediated merge gets an evidence card; outcomes are
+  published with n and 95% intervals. See [evidence](https://github.com/hivecommons/hive/blob/v5/src/docs/evidence.md) and
+  [benchmarks](https://github.com/hivecommons/hive/blob/v5/src/docs/benchmarks/README.md).
+
+## Comparison
+
+| Dimension | Copilot assisted permissions | Hive |
+|---|---|---|
+| Unit of control | One action (command, path, URL) in one session | One GitHub write, one PR, one repository, one lane |
+| Who decides | A second model, then the user | Deterministic config: level, lane allowlist, proxy rules, CI, labels |
+| Where it runs | Inside the Copilot client | Outside the agent, in the proxy and governor; the agent cannot turn it off |
+| Levels | Three modes per session (manual, assisted, allow-all) | Six repository levels, four policy modes per agent |
+| Enterprise controls | Block allow-all, disable assisted, set default mode | Hub-managed level, repo pause, per-lane enforce, auto-merge toggle per repo |
+| What it protects | The developer's machine and the paths and URLs Copilot touches | The repository's issues, PRs, branches, and merges |
+| Unattended runs | Denies what the model will not clear; explanation goes back to the agent | Refuses at the proxy with `403` and a reason; audit entry written |
+| Merge authority | None; Copilot has no view of merges | Only at L6, only on green CI, only in eligible lanes |
+| Human approval step | A prompt per uncleared action | `hold` label and `needs-human` per PR; batch review |
+| Measurement | None published | Refusal counters per tier, evidence cards, shadow-gate records |
+| Model risk | The review model can approve a dangerous action (GitHub's own caveat) | Review verdicts come from models, but every merge still needs deterministic gates |
+| Scope of engines | Copilot only | 15 CLIs through Crux, including Copilot CLI |
+
+## What Copilot does that Hive does not
+
+- Judge a shell command, file path, or URL before it runs. Hive sandboxes the
+  agent and limits network egress, but it does not score individual commands.
+- Reduce prompts for a developer sitting at a terminal. Hive has no interactive
+  prompt step; its agents run unattended.
+- Enterprise-managed defaults that apply to every developer's local session.
+- Ship inside the editor and CLI people already use, with no deployment.
+
+## What Hive does that Copilot does not
+
+- Tie autonomy to repository maturity with a level a team can raise or lower.
+- Refuse a GitHub write at the network layer so an agent cannot talk its way
+  past the rule; the proxy is not a model and does not take explanations.
+- Separate "may open a PR" from "may merge", and gate the merge on CI and
+  review, not on a session mode.
+- Put a `hold` on every agent PR below L6 so humans review in batches.
+- Count refusals and publish merge outcomes with intervals.
+- Run many agents from many vendors under one policy.
+
+## How they fit together
+
+Copilot CLI is one of the engines Hive drives (`copilot` in Crux
+`CLIBackends`). An operator can run Copilot CLI inside Hive with
+`--assisted-approval` for the command-level check, and still have every GitHub
+write go through Hive's proxy and gates. The two layers do not overlap: one
+watches commands, the other watches the repository.
+
+## What this page does not claim
+
+Hive has not measured how often Copilot's review model approves a dangerous
+action, and GitHub does not publish that figure. The 123 refusals above are
+counts from three hives over 15 days, not a rate for anyone else's fleet.
+Neither tool stops a determined person with repository write access.

docs/content/hive/documentation-map.md

@@ -218,6 +218,7 @@ Some documents describe planned or design-only work rather than live features. T
 
 - [Securing your hive: a first-time operator's guide](/docs/hive/securing-your-hive) — decision-oriented walkthrough of ACMM level, reporter trust, and repo scope: starting postures, the #9758/#9762 real-world walk-through, Q&A, a pre-L6 checklist, and a glossary.
 - [Security model — agent safety inventory](/docs/hive/security-model) — threat/control/verification table; runtime, context, credential, code-admission, contributor, detection, platform and human-control layers; residual gaps and running-hive audit steps.
+- [Hive trust levels vs Copilot assisted permissions](/docs/hive/copilot-permissions-comparison) — GitHub Copilot's assisted permissions (GA 2026-10-26) explained from the changelog and docs, next to Hive's ACMM levels, lanes, policy proxy with measured refusal counts, review gates, hold flow and record-only shadow gates; a dimension-by-dimension table and what each side does that the other does not.
 - [Compliance controls](https://github.com/hivecommons/hive/blob/v5/src/docs/compliance.md) — the control registry: framework profiles (SOC 2 Type II, FedRAMP Moderate subset, ISO 27001 Annex A) mapping controls to Hive settings, `GET /api/compliance/status` with meets/deviates/off/not_covered per control, the generated per-framework mapping tables, posture checks, exports and attestations as designed, and the gaps Hive does not cover. Not a certification.
 - [Security threat model](/docs/hive/security-threat-model) — actors, boundaries, layered defenses, known gaps, and reporting.
 - [OSS Scanner threat model](https://github.com/hivecommons/hive/blob/v5/.oss-scanner/threat_model.md) — the scanner-facing companion kept at the repository root with [its Dockerfile](https://github.com/hivecommons/hive/blob/v5/.oss-scanner/Dockerfile): where untrusted input enters, which packages matter most, how to exercise a hive offline, and the severity rubric used to triage findings from [Anthropic's OSS Scanner](https://red.anthropic.com/oss-scanner/).

docs/content/hive/readme.md

@@ -52,6 +52,7 @@ Start with [Zero to Automation: Getting Started with Hive](/docs/hive/getting-st
   or assignment helpers.
 - [Release channels](/docs/hive/release-channels) — what `stable`, `candidate`, and `edge` each mean and what to expect from them.
 - [Security model](/docs/hive/security-model) — agent safety control inventory, threats, enforcement modes, residual gaps and operator audit checklist.
+- [Hive trust levels vs Copilot assisted permissions](/docs/hive/copilot-permissions-comparison) — what GitHub's per-action permission mode (GA 2026-10-26) does, what Hive's levels, lanes, proxy and gates do, and where each covers ground the other does not.
 - Security docs rule: `SECURITY.md` and every `src/docs/security*.md` / `ioscan*.md` page, plus `landscape.md`, must score Flesch-Kincaid grade 11 or lower (CI: `src/scripts/check-security-docs-readability.sh`).
 - Security docs rot rule: the same pages carry a `Last reviewed: YYYY-MM-DD` line in their first 15 lines, no older than 120 days, and may not say an item is "tracked in" / "in progress" / "planned" against an issue that is already closed (CI: `src/scripts/check-security-docs-rot.sh`).
 - [Data collection and telemetry](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md)

scripts/sync-hive-docs.ts

@@ -59,6 +59,7 @@ const files: Array<{ source: string; target?: string; route?: string }> = [
   { source: "integrations/clanker-flue.md" },
   { source: "integrations/spektacular.md" },
   { source: "public-knowledge-mcp.md" },
+  { source: "copilot-permissions-comparison.md" },
   { source: "adr/README.md", target: "adr/readme.md" },
   { source: "adr/0001-record-architecture-decisions.md" },
   { source: "adr/0002-mitm-proxy-network-enforcement.md" },

src/app/docs/page-map.ts

@@ -153,6 +153,7 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [
       { 'Securing your hive': 'securing-your-hive.md' },
       { 'Security model': 'security-model.md' },
       { 'Security threat model': 'security-threat-model.md' },
+      { 'Hive trust levels vs Copilot assisted permissions': 'copilot-permissions-comparison.md' },
       { 'ACMM policy matrix': 'acmm-policy-matrix.md' },
     ]
   },