docs(spec-loop): sync specs with contributed functionality

tools/spec-loop/.last-sync

@@ -1 +1 @@
-dd18a3ccfdff1fc258fd4784970018fcc1c7bb91
+821e564d49883b793c2cf3cb0d4d12b39adb56ab

tools/spec-loop/specs/adapters.md

@@ -2,15 +2,19 @@
      https://www.apache.org/licenses/LICENSE-2.0 -->
 
 ---
-title: Adapters (Gmail / PonyMail / Jira / GitHub / mail-source)
+title: Adapters (Gmail / PonyMail / Jira / GitHub / mail-source / SourceHut / maildir / VCS / change-request)
 status: experimental
 kind: feature
 mode: infra
 source: >
   MISSION.md § Rationale ("ASF integrations live behind clean
   configuration boundaries; non-ASF adopters swap them") and § Technical
   scope (extensible adapter layer). Implemented in tools/gmail/,
-  tools/ponymail/, tools/jira/, tools/github/, tools/mail-source/.
+  tools/ponymail/, tools/jira/, tools/github/, tools/mail-source/,
+  tools/sourcehut/, tools/maildir/, tools/vcs/, tools/change-request/,
+  tools/asf-svn/, tools/mail-archive/, tools/mail-patch/,
+  tools/jira-patch/, tools/forwarder-relay/, tools/github-body-field/,
+  tools/github-rollup/.
 acceptance:
   - Project-specific integrations live behind adapter modules, not
     hardcoded into skills.
@@ -20,7 +24,7 @@ acceptance:
     redactor before any LLM read.
 ---
 
-# Adapters (Gmail / PonyMail / Jira / GitHub)
+# Adapters (Gmail / PonyMail / Jira / GitHub / SourceHut / maildir / VCS / change-request)
 
 ## What it does
 
@@ -33,16 +37,52 @@ by swapping the adapter, not the skill.
 
 - `tools/gmail/` — private-mail read/draft (drafts to the outbox; never
   sends).
+- `tools/maildir/` — private-mail drafting to a local Maildir spool; an
+  offline alternative to Gmail when no cloud mail backend is available.
 - `tools/ponymail/` — public mailing-list archive search.
+- `tools/mail-archive/` — static mailing-list archive reader for
+  projects whose list history is in a local mbox/Maildir export.
 - `tools/jira/` — issue-tracker adapter for projects on Jira.
 - `tools/github/` — issues/PRs/labels read + write-back helpers.
+  Sub-adapters: `tools/github-body-field/` (reads GitHub issue/PR body
+  structured field sets) and `tools/github-rollup/` (aggregates
+  multi-repo PR state into a single view).
+- `tools/sourcehut/` — SourceHut (sr.ht) forge bridge: ticket tracking
+  (`todo.sr.ht`), mailing-list patchset review (`lists.sr.ht`), CI build
+  status (`builds.sr.ht`), and repository reads (`git.sr.ht`/`hg.sr.ht`)
+  via GraphQL. Capability: `contract:tracker + contract:source-control +
+  contract:mail-archive`.
+- `tools/asf-svn/` — ASF Subversion distribution backend: staging area
+  reads, `svn` command-sequence generation for releases and KEYS updates.
+  Never runs `svn commit`; emits paste-ready commands for the Release
+  Manager.
+- `tools/vcs/` (`magpie-vcs`) — unified CLI over the abstract
+  source-control capability (`contract:source-control`). Dispatches
+  branch, stage, commit, diff, log, fetch, and push operations to the
+  active VCS backend (Git today), so skills call the abstract operation
+  and the backend is detected from the working copy or forced with
+  `--backend`/`$MAGPIE_VCS`.
+- `tools/change-request/` — Markdown contract spec for the
+  `contract:change-request` capability (PR / MR abstraction). Declares
+  the interface: `list_open`, `get`, `get_discussion`, `post_review`,
+  `land`, `reject`, `status`. Consumed by PR-management skills; the
+  active implementation is the adapter named by `change_request.backend`
+  in `project.md` (ASF default: `tools/github/`).
 - `tools/mail-source/` — abstract mail backend contract (operations,
   capability matrix, adopter-declaration syntax) with concrete IMAP and
   mbox implementations. Skills (`security-issue-import`,
   `security-issue-sync`, `security-cve-allocate`) address every mail
   source through this contract rather than calling Gmail or PonyMail
   directly; the adopter's `<project-config>/project.md → Mail sources`
   section declares which backends are active and what role each plays.
+- `tools/forwarder-relay/` — relay adapter for security reports forwarded
+  by an upstream broker (e.g. the ASF security team); the counterpart to
+  direct-intake adapters for the `security-issue-import-via-forwarder`
+  sub-skill.
+- `tools/mail-patch/` and `tools/jira-patch/` — patch-over-mail /
+  patch-over-Jira adapters; implement `contract:change-request` for
+  projects that land patches via mailing-list review or Jira rather than
+  GitHub PRs.
 
 ## Behaviour & contract
 
@@ -86,15 +126,19 @@ by swapping the adapter, not the skill.
 ## Validation
 
 ```bash
-for t in gmail ponymail jira github; do
+for t in gmail maildir ponymail jira github; do
   uv run --project tools/$t --group dev pytest || echo "check tools/$t test setup"
 done
+uv run --project tools/vcs --group dev pytest || echo "check tools/vcs test setup"
 ```
 
 ## Known gaps
 
 - `experimental` overall — adapter coverage varies; a new adopter system
   (e.g. GitLab, a different mail backend) is a gap the plan pass records.
+- **SourceHut adapter is new and untested end-to-end.** `tools/sourcehut/`
+  ships the GraphQL-based bridge (ticket, patchset, CI, repo), but no
+  adopter pilot has exercised it; signal/roster heuristics may change.
 - Adapters cover the *system-swap* case; the broader audit of residual
   ASF coupling across the catalogue, and the capability-flag mechanism for
   workflow branches that no adapter resolves, live in

tools/spec-loop/specs/agent-isolation-sandbox.md

@@ -9,8 +9,9 @@ mode: infra
 source: >
   MISSION.md § Privacy, security and supply-chain integrity ("Clean-
   environment wrapper", "Layered sandbox by default", "Pinned, reviewed,
-  signed dependencies"). Implemented in tools/agent-isolation/, the
-  setup-isolated-setup-* skills, and .claude/settings.json.
+  signed dependencies"). Implemented in tools/agent-isolation/,
+  tools/agent-guard/, tools/permission-audit/, tools/egress-gateway/,
+  the setup-isolated-setup-* skills, and .claude/settings.json.
 acceptance:
   - Every agent subprocess runs inside an OS-level sandbox with default-
     deny filesystem reads and network egress.
@@ -33,6 +34,24 @@ saying "no".
 
 - `tools/agent-isolation/` — the harness (clean-env wrapper +
   sandbox profiles).
+- `tools/agent-guard/` — deterministic pre-execution guard dispatcher
+  (`stdlib`-only). Wired as a `PreToolUse` hook (Claude Code) or a
+  `tool.execute.before` plugin (OpenCode); inspects every shell command
+  before it runs and denies the ones that break a hard framework rule,
+  independent of model memory. The guard decisions live in a single
+  harness-agnostic `dispatch()` core so every wired harness enforces
+  an identical rule set. Capability: `substrate:action-guard`.
+- `tools/permission-audit/` — audits and atomically edits Claude Code's
+  `permissions.allow[]` entries in `.claude/settings.json` and
+  `.claude/settings.local.json`. Backs the `--apply-permission-audit`
+  flag of `/magpie-setup verify` (check 8d). Also handles OpenCode
+  `permission` config via `audit-opencode`. Capability: `substrate:sandbox`.
+- `tools/egress-gateway/` — local HTTP(S) forward proxy for egress
+  control. Framework tools point `HTTPS_PROXY`/`HTTP_PROXY` at it; the
+  gateway rejects any connection to a host not on its allowlist before a
+  socket is opened. Defence-in-depth per RFC-AI-0003: even a
+  prompt-injection reaching for an arbitrary endpoint is blocked at the
+  network layer. Capability: `substrate:sandbox`.
 - `.claude/settings.json` — the `sandbox` block (filesystem
   allow/deny, network `allowedDomains`, `excludedCommands`) and
   `permissions` (`deny` / `ask`).
@@ -82,6 +101,9 @@ cooldown window; bumps are PRs, not silent updates.
 
 ```bash
 uv run --project tools/agent-isolation --group dev pytest
+uv run --project tools/agent-guard --group dev pytest
+uv run --project tools/permission-audit --group dev pytest
+uv run --project tools/egress-gateway --group dev pytest
 python3 -c "import json,sys; s=json.load(open('.claude/settings.json')); \
   asks=' '.join(s['permissions']['ask']); \
   sys.exit(0 if 'git push' in asks and 'gh *' in asks else 1)"
@@ -91,3 +113,6 @@ python3 -c "import json,sys; s=json.load(open('.claude/settings.json')); \
 
 - `stable`; drift shows up when a new state-mutating command is added to a
   skill without a matching `ask` rule — the plan pass flags it.
+- **`tools/agent-guard/` and `tools/egress-gateway/` are new additions**
+  since the last pilot cycle; end-to-end integration with a real adopter
+  session has not yet been exercised.

tools/spec-loop/specs/meta-and-quality-tooling.md

@@ -10,7 +10,9 @@ source: >
   README.md § Skill families (utilities) and AGENTS.md § Reusable skills.
   Implemented by tools/skill-and-tool-validator/, tools/skill-evals/,
   tools/sandbox-lint/, tools/dashboard-generator/, tools/probe-templates/,
-  and the write-skill / list-skills utility skills.
+  tools/pilot-report-validator/, tools/vendor-neutrality-score/,
+  tools/preflight-audit/, tools/spec-inventory/, and the write-skill /
+  list-skills utility skills.
 acceptance:
   - Skill definitions are validated (frontmatter keys name/description/
     license, internal link integrity, placeholder conventions).
@@ -49,6 +51,25 @@ trustworthy as it grows.
 - `tools/spec-inventory/` — deterministic `uv` tool that summarizes
   specs, skills, and tools into a compact routing inventory for spec-loop
   prompts.
+- `tools/pilot-report-validator/` — validates adopter pilot-report files
+  against the required schema defined in `docs/pilot-report-template.md`.
+  Checks required frontmatter keys (`skill`, `date`, `target_repo`,
+  plus family-specific required fields), blocked-preflight list
+  structure, and section presence. Pilot reports are the primary
+  evidence source for advancing a skill from `experimental` to `stable`.
+  Capability: `substrate:framework-dev`. Stdlib-only, offline.
+- `tools/vendor-neutrality-score/` — deterministic `uv` tool that scores
+  Magpie's vendor neutrality from repository metadata alone (no network,
+  no model calls). For each capability contract, answers: does Magpie
+  already work across more than one vendor, and is any skill locked to a
+  vendor with no alternative? Reads `tools/*/README.md` and
+  `skills/*/SKILL.md` locally. Capability: `substrate:framework-dev +
+  substrate:analytics`.
+- `tools/preflight-audit/` — dry-runs the bulk-mode pre-flight classifier
+  in live mode (via `gh api graphql`) or replay mode (offline, from a
+  cached snapshot) against a real tracker. Measures skip-rate before and
+  after any rule change, closing the tune-then-verify loop so rule edits
+  are backed by evidence. Capability: `substrate:analytics`.
 - `tools/spec-validator/` — validates spec-loop spec frontmatter
   (required keys, valid `status`/`kind`/`mode` values, body-section
   presence, `Known gaps` section required in functional specs,
@@ -133,6 +154,11 @@ uv run --project tools/spec-inventory --group dev pytest tools/spec-inventory/te
   drift from skill frontmatter.
 - **Tool README prerequisites vary.** A prerequisites consistency pass
   should normalize older tool READMEs before tightening the validator.
-- **Pilot evidence has no common shape.** Experimental-family specs all
-  need adopter evidence, but there is no standard pilot-report template
-  or helper yet.
+- **Pilot evidence shape is now defined and validated.** `docs/pilot-report-template.md`
+  defines the required frontmatter schema and body sections; `tools/pilot-report-validator/`
+  enforces the schema on every `.md` file with a YAML frontmatter block.
+  The "no common shape" gap is closed; the remaining gap is adoption —
+  no adopter pilot has yet submitted a validated report against the template.
+- **Vendor-neutrality measurement is available but unscheduled.** `tools/vendor-neutrality-score/`
+  ships and can be run ad hoc, but is not yet wired into CI or the
+  build loop. Score drift is not automatically surfaced.

tools/spec-loop/specs/overview.md

@@ -51,7 +51,7 @@ Each mode is an independently toggleable set of skills. Maturity mirrors
 | CVE tooling | [cve-tooling.md](cve-tooling.md) |
 | Security reporting & dashboards | [security-reporting.md](security-reporting.md) |
 | Adoption & setup | [adoption-and-setup.md](adoption-and-setup.md) |
-| Adapters (Gmail / PonyMail / Jira / GitHub / mail-source / forwarder-relay / mail-archive / github-body-field / github-rollup) | [adapters.md](adapters.md) |
+| Adapters (Gmail / maildir / PonyMail / Jira / GitHub / SourceHut / VCS / change-request / mail-source / asf-svn / forwarder-relay / mail-archive / mail-patch / jira-patch / github-body-field / github-rollup) | [adapters.md](adapters.md) |
 | Project-agnosticism (de-ASF coupling) | [project-agnosticism.md](project-agnosticism.md) |
 | Meta & quality tooling | [meta-and-quality-tooling.md](meta-and-quality-tooling.md) |
 | Spec-loop runner (plan/build/update/consolidate + headless harnesses) | [spec-loop-runner.md](spec-loop-runner.md) |

tools/spec-loop/specs/reviewer-routing.md

@@ -124,3 +124,8 @@ uv run --project tools/skill-evals skill-eval tools/skill-evals/evals/reviewer-r
 - **`experimental` — no adopter pilot has run.** The skill ships but no
   end-to-end routing workflow has been exercised in a live maintainer
   session; signal weights and roster-match heuristics may change.
+- **Temporarily absent from `docs/modes.md` Triage table.** The skill is
+  under active development (Privacy-LLM gate preflight being added to
+  Step 0); it was removed from the Triage table pending that work landing.
+  The skill itself remains at `mode: Triage` and `experimental`; it will
+  re-enter the modes table once the preflight addition is complete.