ayhammouda · ayhammouda · May 30, 2026 · May 30, 2026
@@ -1,15 +1,15 @@
-# CODEOWNERS — forces maintainer review on forbidden-territory paths.
+# CODEOWNERS — requests maintainer visibility on forbidden-territory paths.
 #
 # Source of truth: AGENT-EXECUTION-PIPELINE.md §2 (Forbidden Territory),
 # required by §10 (Pre-flight Checklist).
 #
 # For these rules to be ENFORCED, branch protection on `main` must enable
 # "Require review from Code Owners". CODEOWNERS alone only requests review;
-# branch protection is what blocks merge.
+# branch protection only blocks merge when review rules are enabled.
 #
-# Autonomous agents may NOT modify these paths without explicit human approval
-# (pipeline §2). Any agent PR touching them must add the `🛑 needs-human-review`
-# label and stop short of requesting merge (pipeline §7).
+# Autonomous agents may NOT modify these paths without explicit Vision approval
+# (pipeline §2). Any agent PR touching them must add the `supervisor-review`
+# label and stop short of self-merging (pipeline §7).
 
 # --- Project identity, dependencies, classifiers (only `version` is agent-editable) ---
 /pyproject.toml                                   @ayhammouda

@@ -85,7 +85,7 @@ body:
           `.github/PULL_REQUEST_TEMPLATE/agent.md`.
         - Branch: `agent/<issue-number>-<kebab-summary>`.
         - If blocked: stop, write `WORKING-NOTES.md` on the branch, comment on
-          this issue per pipeline §8. **No PR, no auto-merge, ever.**
+          this issue per pipeline §8. **No PR and no silent scope expansion.**
     validations:
       required: true
   - type: input
@@ -100,9 +100,9 @@ body:
     attributes:
       label: Agent acknowledgements
       options:
-        - label: I will work on a branch, never on `main`, and will not auto-merge.
+        - label: I will work on a branch, never on `main`, and will not self-merge.
           required: true
         - label: I will stop and comment rather than silently expand scope or touch forbidden territory.
           required: true
-        - label: I will add `🛑 needs-human-review` if any pipeline §7 trigger fires.
+        - label: I will add `supervisor-review` if any pipeline §7 trigger fires.
           required: true
@@ -1,6 +1,6 @@
 <!--
 Autonomous-agent PR template. Enforces AGENT-EXECUTION-PIPELINE.md §6.
-PR title MUST match the issue title verbatim. Never request auto-merge.
+PR title MUST match the issue title verbatim. Never self-merge.
 -->
 
 Closes #<issue-number>
@@ -35,8 +35,8 @@ Pending.
 <!-- One paragraph max. If the issue fully prescribed the approach, say so.
      If you cite a design choice NOT in the issue, that is a §7 trigger. -->
 
-## Why this triggered human review
+## Why this triggered supervisor review
 <!-- List any pipeline §7 triggers and explain each. If none, write "None."
-     If any fired: this PR is opened for review only — do NOT request merge,
-     and ensure the `🛑 needs-human-review` label is applied. -->
+     If any fired: this PR is opened for supervisor review only; do not merge it yourself,
+     and ensure the `supervisor-review` label is applied. -->
 None.
diff --git a/.planning/agent-context/cpython-source-sha-pin.md b/.planning/agent-context/cpython-source-sha-pin.md
@@ -1,7 +1,7 @@
 # Agent Context — CPython source SHA pin
 
 > One-read working context for issue `[v0.3.0] ingestion — pin CPython source by commit SHA`.
-> PARTIAL issue: you do the pin + verification; the human writes the SECURITY.md prose.
+> PARTIAL issue: you do the pin + verification; Vision handles the SECURITY.md prose.
 
 ## 1. Roadmap excerpt
 
@@ -48,7 +48,7 @@
 - Use the **dereferenced commit SHA** (peeled tag), not the annotated tag object's
   own SHA — `rev-parse HEAD` after checkout gives the commit; match that.
 - **Do not edit `SECURITY.md`** (forbidden). Draft the threat-model paragraph in
-  the PR body + decision log below for a human to paste.
+  the PR body + decision log below for Vision to apply.
 - A full `build-index` clones over the network and takes minutes — do not gate the
   PR on it. The unit tests cover the config + verification logic offline.
 - Don't bump any tag to a newer CPython point release; pin the SHA of the
@@ -63,5 +63,5 @@
   - 3.13 / v3.13.13 →
   - 3.14 / v3.14.4 →
 - Where/how the verification aborts on mismatch:
-- **Draft SECURITY.md threat-model paragraph (for human to paste):**
+- **Draft SECURITY.md threat-model paragraph (for Vision to apply):**
   >
diff --git a/.planning/agent-context/pyyaml-safe-loader-audit.md b/.planning/agent-context/pyyaml-safe-loader-audit.md
@@ -36,7 +36,7 @@
 
 - **Do not edit `SECURITY.md`** (forbidden). Capture the trust-boundary write-up
   in a new `docs/architecture/YAML-TRUST-BOUNDARY.md` and recommend SECURITY.md
-  wording for a human.
+  wording for Vision.
 - The two `safe_load` sites both also exist as `.pyc` in `__pycache__`; grep
   source dirs only (`src/`, `tests/`), not `__pycache__`.
 - If the codebase is already clean (expected), the deliverable is the **lock-in**
@@ -49,4 +49,4 @@
 - Audit result (clean / findings):
 - Regression test name + what it scans:
 - Trust-boundary doc location:
-- Recommended SECURITY.md wording (for human):
+- Recommended SECURITY.md wording (for Vision):
diff --git a/.planning/agent-context/zstd-cache-codec.md b/.planning/agent-context/zstd-cache-codec.md
@@ -59,7 +59,7 @@
 - **`zstd-dict-v1` has no production dictionary in this issue.** Make the codec
   *work* only when an explicit dictionary object is supplied by tests. The
   cache's default production codec is `'zstd'`. Shipping a trained dictionary
-  artifact is a separate, human-gated follow-up.
+  artifact is a separate, Vision-gated follow-up.
 - Decode must dispatch off the stored `compression` value, never off the current
   default — otherwise old `'none'` rows break the day the default flips.
 

diff --git a/.planning/issues/v0.3.0/00-README.md b/.planning/issues/v0.3.0/00-README.md
@@ -26,14 +26,14 @@ GitHub issue numbers are filled in below as issues are created (post pre-flight)
 ADR-006 (04) leads the ADR work because it unblocks the v0.3.x `format` parameter.
 01 is intentionally delayed until the dependency and dictionary/context API prep
 are resolved by a maintainer. 06 trails; it is PARTIAL and **must** carry
-`🛑 needs-human-review` because it produces SECURITY.md wording for a human and
+`supervisor-review` because it produces SECURITY.md wording for Vision and
 touches the supply-chain path.
 
-## Explicitly NOT in the agent wave (human-led, roadmap §9.1)
+## Explicitly NOT in the agent wave (Vision-led, roadmap §9.1)
 
 - **30-minute TOON Python port audit** — subjective quality judgment.
 - **Empirical token study** — methodology + corpus selection require judgment.
-  (An agent *may* later scaffold the harness against a human-written
+  (An agent *may* later scaffold the harness against a Vision-written
   `docs/architecture/TOKEN-STUDY-METHODOLOGY.md`, but that spec doesn't exist yet.)
 
 ## Pre-flight checklist (pipeline §10) — status
@@ -42,12 +42,11 @@ touches the supply-chain path.
       `.github/ISSUE_TEMPLATE/autonomous-agent.yml`, `.github/PULL_REQUEST_TEMPLATE/agent.md`,
       `.github/CODEOWNERS` created. **(Land these on `main` before queueing.)**
 - [ ] §5 canonical gate passes on `main` from a clean clone (maintainer to confirm).
-- [ ] Each issue read end-to-end by a human and labeled `agent-ready`.
-- [x] `🛑 needs-human-review` and `agent-ready` labels created in the repo.
-- [x] CODEOWNERS forces review on `pyproject.toml`, `.github/workflows/`, `LICENSE`,
+- [ ] Each issue pre-flighted by Vision and labeled `agent-ready`.
+- [x] `supervisor-review` and `agent-ready` labels created in the repo.
+- [x] CODEOWNERS requests owner visibility on `pyproject.toml`, `.github/workflows/`, `LICENSE`,
       `README.md`, `.planning/POSITIONING.md`, `schema.sql` (and more — see file).
-- [ ] Branch protection on `main` requires ≥1 human approval + "Require review
-      from Code Owners" (maintainer to confirm in repo settings).
+- [ ] Branch protection on `main` keeps deletion and force-push protection active without review deadlock.
 - [x] At least one issue ≤4h for a confidence-building first run: 02 (~1h), 03 (~1–1.5h).
 
 ## Per-issue maintainer pre-reqs
@@ -59,6 +58,6 @@ touches the supply-chain path.
 
 Issues #46–#51 were created from the files in this directory with
 `gh issue create -F .planning/issues/v0.3.0/<file>.md`, after `agent-ready` and
-`🛑 needs-human-review` labels were created in the repo. Do **not** re-run that
+`supervisor-review` labels were created in the repo. Do **not** re-run that
 loop — it would duplicate live issues. Edit the spec file *and* the GitHub
 issue body when a change is needed.
diff --git a/.planning/issues/v0.3.0/01-zstd-cache-codec.md b/.planning/issues/v0.3.0/01-zstd-cache-codec.md
@@ -7,7 +7,7 @@
 ## ⛔ Blocking pre-requisite (maintainer, before queueing)
 
 This task needs the `zstandard` runtime dependency, and `pyproject.toml [project]`
-is **forbidden territory** (pipeline §2) plus a §7 human-review trigger. The
+is **forbidden territory** (pipeline §2) plus a §7 supervisor-review trigger. The
 maintainer must add it and refresh the lockfile **before** this issue is queued:
 
 ```toml
@@ -51,7 +51,7 @@ codec that reads pre-existing uncompressed rows transparently.
 - Tests under `tests/cache/`.
 
 **Out of scope (do NOT do these — stop and comment if they seem required):**
-- Training and **packaging a production `zstd-dict-v1` dictionary** from a real `get_docs` corpus — corpus selection is a human judgment call per roadmap §4. The `zstd-dict-v1` codec must *function* with an explicit dictionary object supplied by tests, but no production dictionary artifact ships in this issue.
+- Training and **packaging a production `zstd-dict-v1` dictionary** from a real `get_docs` corpus — corpus selection is a Vision judgment call per roadmap §4. The `zstd-dict-v1` codec must *function* with an explicit dictionary object supplied by tests, but no production dictionary artifact ships in this issue.
 - Any change to the **canonical index** schema (`src/mcp_server_python_docs/storage/schema.sql`).
 - Any tool name, parameter, or return shape.
 - Compressing `get_docs` markdown on the wire — this is cache-at-rest only.
@@ -75,8 +75,8 @@ uv run pytest tests/test_stdio_smoke.py -q
 ## PR template & recovery
 
 - PR body uses `.github/PULL_REQUEST_TEMPLATE/agent.md`; title matches this issue verbatim.
-- Adding a third-party runtime dep is a §7 trigger — but if the maintainer pre-added `zstandard`, the PR itself introduces no new dep; state that under "Why this triggered human review: None."
-- Blocked? Stop, write `WORKING-NOTES.md`, comment per pipeline §8. No PR, no auto-merge.
+- Adding a third-party runtime dep is a §7 trigger — but if the maintainer pre-added `zstandard`, the PR itself introduces no new dep; state that under "Why this triggered supervisor review: None."
+- Blocked? Stop, write `WORKING-NOTES.md`, comment per pipeline §8. No PR, no silent scope expansion.
 
 ## Effort estimate
 

diff --git a/.planning/issues/v0.3.0/02-readme-glama-six-tool-refresh.md b/.planning/issues/v0.3.0/02-readme-glama-six-tool-refresh.md
@@ -38,7 +38,7 @@ Make every public-facing surface consistently describe the six-tool surface
 
 - `README.md` hero section — do not touch.
 - `pyproject.toml [project]` — do not touch.
-- This PR will touch `README.md`, `.github/RELEASE.md`, and `glama.json`, all of which are CODEOWNERS-owned. Expect required maintainer review; that is correct, not a defect.
+- This PR will touch `README.md`, `.github/RELEASE.md`, and `glama.json`, all of which are CODEOWNERS-owned. Expect supervisor review when triggered; Vision may merge after verification and green checks.
 
 ## Validation commands (pipeline §5)
 
@@ -51,7 +51,7 @@ uv run pytest tests/test_packaging.py -q
 
 ## PR template & recovery
 
-- Use `.github/PULL_REQUEST_TEMPLATE/agent.md`. Under "Why this triggered human review", note: "Touches CODEOWNERS-owned brand/release docs (`README.md`, `.github/RELEASE.md`); opened for review, not auto-merge."
+- Use `.github/PULL_REQUEST_TEMPLATE/agent.md`. Under "Why this triggered supervisor review", note: "Touches CODEOWNERS-owned brand/release docs (`README.md`, `.github/RELEASE.md`); opened for supervisor review."
 - Blocked? Stop, `WORKING-NOTES.md`, comment per §8.
 
 ## Effort estimate

diff --git a/.planning/issues/v0.3.0/03-pyyaml-safe-loader-audit.md b/.planning/issues/v0.3.0/03-pyyaml-safe-loader-audit.md
@@ -32,7 +32,7 @@ via `yaml.safe_load`, with the trust boundary documented and regression-guarded.
 
 ## Forbidden-territory reminders (pipeline §2)
 
-- `SECURITY.md` — trust-posture prose requires deliberate human review. Capture findings in a new `docs/architecture/` note instead and recommend the `SECURITY.md` wording for a human to apply.
+- `SECURITY.md` — trust-posture prose requires deliberate Vision review. Capture findings in a new `docs/architecture/` note instead and recommend the `SECURITY.md` wording for Vision to apply.
 - Existing tests — extend, never weaken.
 
 ## Validation commands (pipeline §5)

diff --git a/.planning/issues/v0.3.0/06-cpython-source-sha-pin.md b/.planning/issues/v0.3.0/06-cpython-source-sha-pin.md
@@ -1,6 +1,6 @@
 # [v0.3.0] ingestion — pin CPython source by commit SHA
 
-> **Confidence:** PARTIAL (agent does the pin; human writes the SECURITY.md threat model) · **Wave:** trailing · **Slug:** `cpython-source-sha-pin`
+> **Confidence:** PARTIAL (agent does the pin; Vision handles the SECURITY.md threat model) · **Wave:** trailing · **Slug:** `cpython-source-sha-pin`
 > Create with: `gh issue create -F .planning/issues/v0.3.0/06-cpython-source-sha-pin.md -l area:build,compliance,priority:P1`
 > Branch: `agent/<issue-number>-cpython-source-sha-pin`
 
@@ -21,7 +21,7 @@ Make a pinned commit SHA — not a mutable tag — the integrity anchor for ever
 - [ ] After the clone in `__main__.py`, the code verifies `git -C <clone_dir> rev-parse HEAD` equals `config["sha"]` and **aborts that version's build with a clear error** on mismatch (no silent fallback). The shallow `--branch <tag>` fetch may stay; the SHA check is what enforces integrity.
 - [ ] `tests/test_ingestion.py` asserts every config entry has a `sha` matching `^[0-9a-f]{40}$`, alongside the existing tag assertion at line 53.
 - [ ] `uv run pytest tests/test_ingestion.py -q` passes.
-- [ ] A draft SECURITY.md threat-model paragraph (the `build-index` CPython clone as the largest non-runtime attack surface, now SHA-pinned) is written **into the PR description and the context file's decision log** for a human to paste — `SECURITY.md` itself is **not** edited.
+- [ ] A draft SECURITY.md threat-model paragraph (the `build-index` CPython clone as the largest non-runtime attack surface, now SHA-pinned) is written **into the PR description and the context file's decision log** for Vision to apply — `SECURITY.md` itself is **not** edited.
 
 ## Scope boundaries
 
@@ -34,7 +34,7 @@ Make a pinned commit SHA — not a mutable tag — the integrity anchor for ever
 
 ## Forbidden-territory reminders (pipeline §2)
 
-- `SECURITY.md` — do not edit; provide draft text for human review (this is the "human" half of this PARTIAL issue).
+- `SECURITY.md` — do not edit; provide draft text for Vision review (this is the "Vision" half of this PARTIAL issue).
 - `.github/workflows/` — do not touch the release/CI path.
 - `pyproject.toml [project]` — untouched.
 
@@ -53,7 +53,7 @@ uv run python-docs-mcp-server validate-corpus
 
 ## PR template & recovery (pipeline §6, §7)
 
-- This is a **human-review-required** PR: it touches the supply-chain integrity path and produces SECURITY.md wording for a human. Open the PR, add `🛑 needs-human-review`, do **not** request merge. Fill the "Why this triggered human review" section.
+- This is a **supervisor-review-required** PR: it touches the supply-chain integrity path and produces SECURITY.md wording for Vision. Open the PR, add `supervisor-review`, do not self-merge. Fill the "Why this triggered supervisor review" section.
 - Blocked (e.g. can't resolve a SHA offline)? Stop and comment per §8.
 
 ## Effort estimate