diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync index 1dd08632..e63ff595 100644 --- a/tools/spec-loop/.last-sync +++ b/tools/spec-loop/.last-sync @@ -1 +1 @@ -dd18a3ccfdff1fc258fd4784970018fcc1c7bb91 +821e564d49883b793c2cf3cb0d4d12b39adb56ab diff --git a/tools/spec-loop/specs/adapters.md b/tools/spec-loop/specs/adapters.md index 36e589ae..c8e5fe68 100644 --- a/tools/spec-loop/specs/adapters.md +++ b/tools/spec-loop/specs/adapters.md @@ -2,7 +2,7 @@ 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 @@ -10,7 +10,11 @@ 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,9 +37,37 @@ 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`, @@ -43,6 +75,14 @@ by swapping the adapter, not the skill. source through this contract rather than calling Gmail or PonyMail directly; the adopter's `/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 diff --git a/tools/spec-loop/specs/agent-isolation-sandbox.md b/tools/spec-loop/specs/agent-isolation-sandbox.md index b63e8a91..cc373454 100644 --- a/tools/spec-loop/specs/agent-isolation-sandbox.md +++ b/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. diff --git a/tools/spec-loop/specs/meta-and-quality-tooling.md b/tools/spec-loop/specs/meta-and-quality-tooling.md index 64fa70dd..1ac0a3d2 100644 --- a/tools/spec-loop/specs/meta-and-quality-tooling.md +++ b/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. diff --git a/tools/spec-loop/specs/overview.md b/tools/spec-loop/specs/overview.md index 4a00a6b0..79a5e651 100644 --- a/tools/spec-loop/specs/overview.md +++ b/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) | diff --git a/tools/spec-loop/specs/reviewer-routing.md b/tools/spec-loop/specs/reviewer-routing.md index b9e39fc1..11b9f2cd 100644 --- a/tools/spec-loop/specs/reviewer-routing.md +++ b/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.