python-docs-mcp-server 0.2.1__tar.gz → 0.3.1__tar.gz

python_docs_mcp_server-0.3.1/.coderabbit.yaml

@@ -0,0 +1,24 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+
+reviews:
+  profile: "chill"
+  request_changes_workflow: false
+  high_level_summary: true
+  review_status: true
+  path_filters:
+    - "src/**"
+    - "tests/**"
+  path_instructions:
+    - path: "src/**"
+      instructions: |
+        Focus review on correctness, MCP tool behavior, runtime compatibility,
+        cache/index compatibility, packaging impact, and security boundaries.
+        Avoid comments about planning docs, release docs, or repository process
+        unless the changed source code makes those docs materially inaccurate.
+    - path: "tests/**"
+      instructions: |
+        Focus review on meaningful assertions, regression coverage, fixture
+        correctness, deterministic behavior, and avoiding network- or
+        environment-dependent tests unless the test is explicitly marked as an
+        integration smoke test.

python_docs_mcp_server-0.3.1/.github/CODEOWNERS

@@ -0,0 +1,49 @@
+# 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 only blocks merge when review rules are enabled.
+#
+# 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
+
+# --- Permanent commitments and trust posture ---
+/LICENSE                                          @ayhammouda
+/SECURITY.md                                      @ayhammouda
+
+# --- Load-bearing brand assets ---
+/README.md                                        @ayhammouda
+/.planning/POSITIONING.md                         @ayhammouda
+
+# --- Release history (adding entries is fine; rewriting history is not) ---
+/CHANGELOG.md                                     @ayhammouda
+
+# --- CI/CD and supply chain (release path especially) ---
+# The single /.github/ rule covers workflows and release.yml. Last-matching-
+# pattern wins in CODEOWNERS — adding narrower entries with the same owner
+# below would be no-ops and would silently *override* this rule if a different
+# owner is ever added here, so we keep ownership of /.github/ uniform.
+/.github/                                         @ayhammouda
+
+# --- Index schema and migrations (rebuilds existing user indexes) ---
+# NOTE: the retrieved-docs *cache* table lives in
+# src/mcp_server_python_docs/services/persistent_cache.py and is NOT covered
+# here — it is best-effort, fingerprint-scoped, and agent-editable per
+# decision 5.7. Only the canonical *index* schema is forbidden territory.
+**/storage/schema.sql                             @ayhammouda
+**/migrations/                                    @ayhammouda
+
+# --- Archival roadmap history ---
+/.planning/ROADMAP.md                             @ayhammouda
+
+# --- Governing policy + strategy documents ---
+/AGENT-EXECUTION-PIPELINE.md                      @ayhammouda
+/OPENCLAW-FORGE-PROTOCOL.md                       @ayhammouda
+/STRATEGIC-ROADMAP-2026-05-29.md                  @ayhammouda

python_docs_mcp_server-0.3.1/.github/ISSUE_TEMPLATE/autonomous-agent.yml

@@ -0,0 +1,108 @@
+name: Autonomous Agent Task
+description: A task spec scoped for unattended execution by an autonomous coding agent (Claude Code or similar).
+title: "[vX.Y.Z] <scope> — <verb> <thing>"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template enforces the issue structure required by
+        `AGENT-EXECUTION-PIPELINE.md` §3 (in the repo root). An issue missing
+        any required section is **not** agent-ready and will not pass the §10
+        pre-flight checklist. Do not apply the `agent-ready` label from this
+        template; a maintainer applies it only after reading the completed
+        issue end-to-end. Read the pipeline doc and
+        `STRATEGIC-ROADMAP-2026-05-29.md` before filling this out.
+  - type: textarea
+    id: context
+    attributes:
+      label: Context (self-containment)
+      description: Link to the per-issue context file, this pipeline doc, the roadmap, any relevant ADR or `.planning/phases/0X-*` directory, and prior related issues.
+      value: |
+        - Per-issue context file: `.planning/agent-context/<issue-slug>.md` (read this first)
+        - Pipeline: `AGENT-EXECUTION-PIPELINE.md`
+        - Roadmap: `STRATEGIC-ROADMAP-2026-05-29.md` §<section>
+        - Related issues:
+    validations:
+      required: true
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal (one sentence)
+      description: The single outcome that counts as success.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria (testable checkbox list)
+      description: Each criterion must be testable, atomic, achievable without touching forbidden territory, and verifiable in <5 minutes (pipeline §4). Prefer exact commands and expected output.
+      value: |
+        - [ ] `<exact command>` <expected result>
+        - [ ] `<exact command>` <expected result>
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope boundaries
+      description: Explicit In scope / Out of scope. Out-of-scope work is a stop-and-comment trigger, never silent expansion.
+      value: |
+        **In scope:**
+        -
+
+        **Out of scope:**
+        -
+    validations:
+      required: true
+  - type: textarea
+    id: forbidden
+    attributes:
+      label: Forbidden-territory reminders
+      description: Repeat the AGENT-EXECUTION-PIPELINE.md §2 items relevant to THIS issue. If the task appears to require touching any of them, stop and comment.
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation commands (pipeline §5 gate)
+      description: The exact canonical gate, in order, plus any change-type-specific gates. Must pass before any PR is opened.
+      value: |
+        ```bash
+        uv run ruff check src/ tests/
+        uv run pyright src/
+        uv run pytest --tb=short -q
+        uv run python-docs-mcp-server doctor
+        ```
+    validations:
+      required: true
+  - type: textarea
+    id: pr-and-recovery
+    attributes:
+      label: PR requirements & recovery
+      description: What the PR description must include (pipeline §6) and where to go if blocked (pipeline §8).
+      value: |
+        - PR title matches this issue title verbatim; body uses
+          `.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 and no silent scope expansion.**
+    validations:
+      required: true
+  - type: input
+    id: effort
+    attributes:
+      label: Effort estimate (hours)
+      description: Rough hours. Agent must bail and escalate if work exceeds 2× this estimate (pipeline §8).
+    validations:
+      required: true
+  - type: checkboxes
+    id: acknowledgements
+    attributes:
+      label: Agent acknowledgements
+      options:
+        - 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 `supervisor-review` if any pipeline §7 trigger fires.
+          required: true

python_docs_mcp_server-0.3.1/.github/PULL_REQUEST_TEMPLATE/agent.md

@@ -0,0 +1,42 @@
+<!--
+Autonomous-agent PR template. Enforces AGENT-EXECUTION-PIPELINE.md §6.
+PR title MUST match the issue title verbatim. Never self-merge.
+-->
+
+Closes #<issue-number>
+
+## Acceptance criteria
+<!-- Copy every criterion from the issue. Check the box only when satisfied,
+     and add one line of evidence (command + observed result) per item. -->
+- [ ] <criterion 1> — <evidence>
+- [ ] <criterion 2> — <evidence>
+
+## Validation gate output
+<!-- Paste the tail of each gate command. All must be green before opening this PR. -->
+```text
+$ uv run ruff check src/ tests/
+$ uv run pyright src/
+$ uv run pytest --tb=short -q
+$ uv run python-docs-mcp-server doctor
+```
+<!-- Plus any change-type-specific gates from pipeline §5 (stdio smoke,
+     validate-corpus, uv lock --check) that applied to this change. -->
+
+## CodeRabbit review
+<!-- After CodeRabbit comments, summarize findings as:
+     - Blocking: <items or None>
+     - Follow-up: <items or None>
+     - False positive: <items or None>
+     If CodeRabbit has not run yet, write "Pending." Do not mark findings green
+     by silence. -->
+Pending.
+
+## Why this approach
+<!-- 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 supervisor review
+<!-- List any pipeline §7 triggers and explain each. If none, write "None."
+     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.

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/RELEASE.md

@@ -51,6 +51,7 @@ Replace `X.Y.Z` below with the version you are releasing (e.g. `0.1.7`). Complet
   ```
   Must report `✅ server.json is valid`. If validation fails, shorten `server.json` `description` on `main` before tagging (the `pyproject.toml` description is unbounded by this constraint and can stay longer).
 - [ ] Integration tests from `.github/INTEGRATION-TEST.md` are complete and signed off
+- [ ] Refresh README `## Tools`, `glama.json`, and registry/version badges to match the current tool surface.
 - [ ] `Doctor` subcommand passes:
   ```bash
   uv run python-docs-mcp-server doctor

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
     name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           cache-suffix: py${{ matrix.python-version }}
 

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/codeql.yml

@@ -22,7 +22,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/e2e.yml

@@ -17,10 +17,10 @@ jobs:
         python-version: ["3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           cache-suffix: py${{ matrix.python-version }}
 

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/release.yml

@@ -16,10 +16,10 @@ jobs:
     timeout-minutes: 15
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Set up Python 3.13
         run: uv python install 3.13
@@ -117,7 +117,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install mcp-publisher
         run: |

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/scorecard.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
 

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.github/workflows/security.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Export locked dependencies
         run: |

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/.gitignore

@@ -194,6 +194,9 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+# Local planning / agent workspace
+.planning/
+
 # Cursor
 #  Keep repo-local Cursor context files tracked when present so the repository
 #  can define its own indexing boundaries.

python_docs_mcp_server-0.3.1/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "python-docs": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["python-docs-mcp-server"]
+    }
+  }
+}

python_docs_mcp_server-0.3.1/AGENT-EXECUTION-PIPELINE.md

@@ -0,0 +1,287 @@
+# Autonomous Agent Execution Pipeline
+
+**Purpose:** Define the policy, context, and guardrails for running autonomous coding agents (Claude Code or similar) against this project's GitHub issues while the maintainer is AFK.
+
+**Companion to:** [`STRATEGIC-ROADMAP-2026-05-29.md`](STRATEGIC-ROADMAP-2026-05-29.md) (the *what*; this is the *how, with what guardrails*).
+
+**OpenClaw operating layer:** [`OPENCLAW-FORGE-PROTOCOL.md`](OPENCLAW-FORGE-PROTOCOL.md) defines how Vision, Gilfoyle, and Heimdall apply this policy. This project has no UI, so Saga is not part of the default loop.
+
+**Adopted:** 2026-05-29
+
+---
+
+## 1. Operating Principles
+
+- Agents work in branches, never on `main`.
+- Every PR requires independent verification before merge. Vision may merge verified PRs when checks and review triage are green.
+- Agents declare their scope explicitly and stay inside it.
+- The canonical validation gate (§5) must pass before any PR is opened. Failing gate → no PR, just a `WORKING-NOTES.md` on the branch + comment on the issue.
+- Automated review tools such as CodeRabbit provide review signal only. They do not approve or merge; Vision uses them as review signal before merging.
+- Forbidden territory (§2) is non-negotiable. Any drift triggers a hard stop.
+- Recovery is always **stop and post a comment**, never **silently expand scope**.
+
+The goal is to keep the forge moving while preserving explicit stop points for money, secrets, external communication, and unresolved architectural judgment.
+
+---
+
+## 2. Forbidden Territory (hard stop)
+
+Autonomous agents may NOT modify the following without explicit Vision approval in the issue comments first:
+
+| Path / Concern | Reason |
+|---|---|
+| Any tool name, parameter, or return shape | Public API surface; semver-significant |
+| `schema.sql` and migrations | Index schema; rebuilds existing user caches |
+| `.github/workflows/` (any workflow) | CI/CD and supply chain |
+| `.github/workflows/release.yml` specifically | Release path; Trusted Publishing config |
+| `pyproject.toml` `[project]` (anything other than `version`) | Identity, dependencies, classifiers |
+| Major dependency bumps (anything ≥1 major) | Compatibility risk |
+| `.planning/POSITIONING.md` | Load-bearing brand asset |
+| `README.md` hero section (above the first install code block) | Load-bearing brand asset |
+| `LICENSE` | Permanent commitment (MIT, always free) |
+| `CHANGELOG.md` (creating entries is fine; rewriting history is not) | Release history |
+| `SECURITY.md` | Trust posture; requires deliberate review |
+| Existing tests (deletion or weakening assertions) | Regression cover |
+| `.planning/ROADMAP.md` historical phase records | Archival history |
+| `AGENT-EXECUTION-PIPELINE.md`, `OPENCLAW-FORGE-PROTOCOL.md`, and `STRATEGIC-ROADMAP-2026-05-29.md` | Governing policy and strategy docs |
+
+If an agent's task appears to require touching any of these:
+1. **Stop work.**
+2. Post a comment on the issue explaining the conflict.
+3. Tag with `supervisor-review`.
+4. Wait for guidance.
+
+---
+
+## 3. Issue Structure (required for every agent-targetable issue)
+
+Every issue intended for an autonomous agent **must** contain these sections, in this order:
+
+| Section | Purpose | Required content |
+|---|---|---|
+| **Title** | Routability | `[v0.X.Y] <scope> — <verb> <thing>` e.g., `[v0.3.0] cache — add zstd codec layer` |
+| **Context** | Self-containment | Links to: this pipeline doc, the strategic roadmap, any specific ADR or `.planning/phases/0X-*` directory, prior related issues |
+| **Goal** | Single sentence | What outcome counts as success |
+| **Acceptance criteria** | Testable definition of done | Checkbox list per §4 |
+| **Scope boundaries** | Prevents creep | "In scope:" and "Out of scope:" subsections |
+| **Forbidden-territory reminder** | Belt and suspenders | Repeat the §2 items relevant to this issue |
+| **Validation commands** | Pre-PR gate | The exact canonical commands per §5 |
+| **PR template** | What the PR description must include | §6 checklist |
+| **Recovery** | What to do if blocked | Pointer to §8 |
+| **Effort estimate** | Sanity check | Rough hours; agent should bail and escalate if work exceeds 2× |
+
+An issue missing any of these is not agent-ready. The pre-flight checklist (§10) gates this.
+
+---
+
+## 4. Acceptance-Criteria Patterns
+
+**Each criterion must be:** testable, atomic, achievable without touching forbidden territory, and sized so a competent dev could verify it in <5 minutes.
+
+**Good examples:**
+
+- "`uv run pytest tests/cache/test_codec.py -q` passes with at least 4 new tests covering: codec round-trip for `'none'`, codec round-trip for `'zstd'`, codec round-trip for `'zstd-dict-v1'`, and graceful read of pre-existing `compression='none'` rows."
+- "After cherry-picking this branch, `python -c 'from mcp_server_python_docs.cache.codec import list_supported; print(list_supported())'` prints exactly `['none', 'zstd', 'zstd-dict-v1']`."
+- "`grep -rn 'yaml.load(' src/ tests/` returns zero hits. `grep -rn 'yaml.safe_load(' src/` returns at least the expected call sites in `server.py` and `ingestion/sphinx_json.py`."
+- "README.md `## Tools` section lists exactly six rows in the table, including `compare_versions`, and the row order matches the `@mcp.tool` declaration order in `src/mcp_server_python_docs/server.py`."
+
+**Bad examples (do not allow):**
+
+- "Improve cache performance." — not testable
+- "Make it production-ready." — not specific
+- "Refactor for clarity." — invites scope creep
+- "Add tests." — what tests, asserting what?
+
+---
+
+## 5. Canonical Validation Gate
+
+**Must pass, in this order, before any PR is opened:**
+
+```bash
+uv run ruff check src/ tests/
+uv run pyright src/
+uv run pytest --tb=short -q
+uv run python-docs-mcp-server doctor
+```
+
+**Additional gates for specific change types:**
+
+- Any change touching the MCP wire protocol or tool registration:
+  ```bash
+  uv run pytest tests/test_stdio_smoke.py -q
+  ```
+- Any change to ingestion or storage:
+  ```bash
+  uv run python-docs-mcp-server validate-corpus
+  ```
+- Any change touching dependencies:
+  ```bash
+  uv lock --check
+  uv pip compile --quiet pyproject.toml -o /tmp/requirements-check.txt
+  ```
+
+**Failure handling:** If any gate fails, the agent writes the full output into a file `WORKING-NOTES.md` at the branch root, commits it as `agent: validation-gate-failed`, posts a comment on the issue with a link to the failing commit, and stops. **No PR is opened.**
+
+---
+
+## 6. Branch, Commit, PR Conventions
+
+- **Branch name:** `agent/{issue-number}-{kebab-case-summary}` (e.g., `agent/47-zstd-cache-codec`)
+- **Commit prefix:** `agent: ` followed by a short, imperative summary. Conventional-commit scopes optional but encouraged: `agent: cache(codec): add zstd round-trip path`
+- **Atomic commits.** One logical change per commit. No squash-and-force-push during agent work.
+- **PR title** matches the issue title verbatim
+- **PR description** must include:
+  - `Closes #<issue-number>` (or `Refs #` if intentionally not closing)
+  - Each acceptance criterion as a checked or unchecked box, with a one-line explanation if unchecked
+  - Output (or link to artifact) for the §5 validation gate
+  - CodeRabbit triage summary when CodeRabbit comments on the PR: blocking, follow-up, false positive, or pending/unavailable
+  - A short "Why this approach" paragraph if the design wasn't fully prescribed in the issue
+  - The §7 "Supervisor review" disclosure (which doubles as a forbidden-territory near-miss log when applicable; CODEOWNERS is the mechanical enforcement)
+- **PR is opened against** the milestone integration branch (e.g., `release/v0.3.0`) when one exists, otherwise `main`. Never self-merge.
+
+---
+
+## 7. Supervisor-Review Triggers (always pause)
+
+The agent must open the PR but **NOT** request merge — and must add the `supervisor-review` label — if any of these are true:
+
+| Trigger | Why |
+|---|---|
+| Any forbidden-territory item (§2) was modified | By definition |
+| Any existing test was deleted | Possible regression-cover loss |
+| Diff exceeds 500 lines of source code (excluding generated and lockfiles) | Bigger than a single agent task should be |
+| A new third-party runtime dependency was introduced | Trust-posture and footprint review |
+| Any `pyproject.toml` field changed (other than `version` during a release issue) | Identity / metadata review |
+| `.github/workflows/` was modified | CI/release-path review |
+| The PR introduces network access at runtime | Violates principle 2.2 (offline-first) |
+| The PR introduces async code in a previously-sync code path | Concurrency review |
+| The agent's "Why this approach" paragraph cites a design choice not in the issue | Verify scope |
+
+For each trigger, the PR description must include a `## Why this triggered supervisor review` section explaining what changed and why the agent believes it was necessary.
+
+---
+
+## 8. Recovery Procedures
+
+If the agent encounters any of these conditions, **stop work** and post a comment on the issue:
+
+- A previously passing test now fails for an unclear reason
+- A change to forbidden territory appears necessary to complete the task
+- The acceptance criteria turn out to be ambiguous or contradictory
+- An upstream dependency is broken or unavailable
+- Work appears to exceed 2× the original effort estimate
+
+The stop comment must contain:
+1. What was attempted (1–3 sentences)
+2. What failed or blocked (with error output if applicable)
+3. The agent's best read on the path forward
+4. An explicit "I am stopping pending guidance" line
+
+**Forbidden recovery moves:**
+
+- Silently expanding scope
+- Trying alternative implementations not specified in the issue
+- Merging to `main`
+- Deleting tests to make others pass
+- Suppressing warnings or skipping tests as a "workaround"
+
+---
+
+## 9. Context Files Required Before Agents Run
+
+These files must exist on `main` before the v0.3.0 issues are unleashed to autonomous agents.
+
+| File | Purpose | Status |
+|---|---|---|
+| [`AGENTS.md`](AGENTS.md) | Existing repo-conventions doc; should reference this pipeline | **Needs update** — add a one-paragraph link to this file |
+| [`STRATEGIC-ROADMAP-2026-05-29.md`](STRATEGIC-ROADMAP-2026-05-29.md) | The *what and why*; mandatory reading | **Exists** |
+| `AGENT-EXECUTION-PIPELINE.md` (this file) | The *how, with what guardrails* | **Exists** |
+| [`OPENCLAW-FORGE-PROTOCOL.md`](OPENCLAW-FORGE-PROTOCOL.md) | OpenClaw role split and MCP-specific execution loop | **Exists** |
+| `.github/ISSUE_TEMPLATE/autonomous-agent.yml` | Issue template enforcing §3 structure | **Create** — see §11 sketch |
+| `.github/PULL_REQUEST_TEMPLATE/agent.md` | PR template enforcing §6 | **Create** — see §11 sketch |
+| `.github/CODEOWNERS` | Requests owner attention on forbidden-territory paths | **Create** — see §11 sketch |
+| `docs/architecture/TOKEN-STUDY-METHODOLOGY.md` | Methodology spec for the v0.3.0 first issue | **Create as part of that issue spec** |
+| GitHub label: `supervisor-review` | Marks PRs paused at §7 triggers | **Create** |
+| GitHub label: `agent-ready` | Confirms issue passed §10 pre-flight | **Create** |
+| Branch protection on `main` | Allows Vision to merge after verification and green checks | **Confirm enabled** |
+| Branch protection on `release/v0.3.0` (when created) | Same | **Configure at branch creation** |
+
+---
+
+## 10. Pre-flight Checklist (run before unleashing agents on a milestone)
+
+Run this checklist before pushing the first agent-ready issue to the queue.
+
+- [ ] All §9 context files exist on `main`.
+- [ ] The §5 canonical validation gate passes on `main` (clean baseline).
+- [ ] Each issue has been pre-flighted by Vision and labeled `agent-ready`.
+- [ ] Each issue includes its §3 sections in full.
+- [ ] The `supervisor-review` and `agent-ready` labels exist in the repo.
+- [ ] CODEOWNERS forces review on at least: `pyproject.toml`, `.github/workflows/`, `LICENSE`, `README.md`, `.planning/POSITIONING.md`, `schema.sql`.
+- [ ] Branch protection on `main` keeps deletion and force-push protection active without review deadlock.
+- [ ] At least one issue is small enough (≤4 hours) to serve as a confidence-building first run.
+
+---
+
+## 11. Templates (authoritative implementations)
+
+The §9 templates live as checked-in files; this section just points at them so
+this doc never drifts from the implementations:
+
+- `.github/ISSUE_TEMPLATE/autonomous-agent.yml`
+- `.github/PULL_REQUEST_TEMPLATE/agent.md`
+- `.github/CODEOWNERS`
+
+---
+
+## 12. Per-Issue Context Files (v0.3.0 wave)
+
+For the first wave of agent-targetable issues, Claude Code should include — as linked references in each issue — a dedicated `.planning/agent-context/<issue-slug>.md` file that captures the agent's working notes, design decisions to honor, and any test fixtures or code excerpts the agent will need to look at.
+
+Each per-issue context file should contain:
+
+1. **The relevant excerpt from `STRATEGIC-ROADMAP-2026-05-29.md`** (don't make the agent re-derive the goal).
+2. **Pointer to the existing code touch-points** (file paths + symbols).
+3. **Existing test patterns to follow** (one or two example tests from the same area).
+4. **Known pitfalls** specific to this task.
+5. **Decision log placeholder** for the agent to fill in.
+
+The point is to give the agent everything it needs in one read, so it doesn't go fishing across the repo and pick up incorrect patterns from `.planning/` archive material.
+
+---
+
+## 13. Suggested Agent-Targetable Issues for v0.3.0
+
+Mapping the v0.3.0 deliverables to agent-friendliness, to help prioritize issue generation:
+
+| Deliverable | Agent-friendly? | Why | Recommended owner |
+|---|---|---|---|
+| Workstream J — zstd cache codec layer | **Yes (high)** | Well-bounded, testable, no API surface change | Agent |
+| README + PyPI + glama.json refresh to 6-tool surface | **Yes (high)** | Mechanical, easily verified, low risk | Agent |
+| PyYAML safe-loader audit | **Yes (medium)** | Simple grep + fix; need agent to surface findings before changing | Agent |
+| ADR-001 (Source Adapters) draft | **Yes (medium)** | Writing task; needs clear template + style guide | Agent with strict template |
+| ADR-006 (Serialization) draft | **Yes (medium)** | Same as ADR-001 | Agent with strict template |
+| Build-time supply-chain hardening (CPython SHA pin + SECURITY.md update) | **Partial** | Pinning is mechanical; SECURITY.md text needs judgment | Agent for pinning; Vision for SECURITY.md |
+| 30-minute TOON Python port audit | **No** | Requires subjective quality judgment | Human |
+| Empirical token study | **No** | Methodology choices and corpus selection require judgment | Human (with agent scaffolding the harness) |
+
+The v0.3.0 issue wave should therefore lead with the **high-confidence agent issues** so the overnight run produces obvious wins, then escalate to the partial / Vision-judgment items the following day under Vision supervision.
+
+---
+
+## Amendments
+
+*Append amendments below as `## Amendment YYYY-MM-DD` sections. Do not edit historical content above this line; the locked sections are the authoritative current policy.*
+
+## Amendment 2026-05-29 — OpenClaw Role Split
+
+OpenClaw execution for this repo is governed by `OPENCLAW-FORGE-PROTOCOL.md`.
+The default loop is Vision → Gilfoyle → Heimdall → Vision/Aymen:
+
+- Vision owns issue pre-flight, `agent-ready`, review synthesis, branch protection, and pause/resume decisions.
+- Gilfoyle owns scoped implementation on exactly one issue at a time.
+- Heimdall owns independent verification, packaging/install smoke, security-sensitive checks, and release-readiness checks.
+- CodeRabbit findings are mandatory review signal when present. Vision/Heimdall must triage them as blocking, follow-up, or false positive before `verified`.
+- Saga is not in the default loop because this MCP has no UI.
+- Pipeline Monitor remains disabled unless Aymen explicitly asks for assisted merge checks; no Vision-owned merge is allowed.

{python_docs_mcp_server-0.2.1 → python_docs_mcp_server-0.3.1}/AGENTS.md

@@ -11,6 +11,19 @@ The repo's public credibility matters. Prefer changes that make the project
 easier to trust, easier to verify, and easier to contribute to over changes
 that merely add more AI or MCP setup.
 
+## Autonomous Agent Execution
+
+A portion of this project is executed by autonomous coding agents working
+unattended against GitHub issues. If you are such an agent — or are scoping
+work for one — **`AGENT-EXECUTION-PIPELINE.md` is mandatory reading before you
+touch anything.** It defines the forbidden territory (don't-touch paths), the
+required issue structure, the canonical validation gate, the human-review
+triggers, and the recovery procedure. The *what and why* lives in
+`STRATEGIC-ROADMAP-2026-05-29.md`; the *how, with what guardrails* lives in the
+pipeline doc. Agents work on branches only, every PR needs human review, and
+auto-merge is forbidden. Per-issue working context lives under
+`.planning/agent-context/<issue-slug>.md`.
+
 ## Canonical Commands
 
 If `uv` is not installed yet:
@@ -87,6 +100,9 @@ Before calling work complete:
 
 - `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` are live,
   forward-looking specs — read these first when starting a new phase.
+- `.planning/agent-context/<issue-slug>.md` and active
+  `.planning/issues/v0.3.0/*.md` specs are live only for autonomous-agent issue
+  execution; read them when an issue or pipeline document links them.
 - Anything else in `.planning/` (especially content dated 2026-04 or earlier)
   is archival history. It may help maintainers reconstruct prior context but
   should not drive routine implementation decisions.