Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion tools/spec-loop/.last-sync
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1e5c4f9110812f1c0bc4bc6312723c9f98c82fca
bfc99bb6f47be727b124adf939e5c010fe33ba5f
21 changes: 19 additions & 2 deletions tools/spec-loop/specs/adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,21 @@ by swapping the adapter, not the skill.
by shelling out to `oauth-draft-create` or probing the token file: the
OAuth token under `~/.config/apache-magpie/` is not readable from
sandboxed Bash, and sandbox-lint refuses an `allowRead` grant for it
(#1681).
(#1681). A draft threads on the inbound message one of three ways
(`tools/gmail/threading.md`): attached to its Gmail `thread_id`, with
`In-Reply-To` / `References` derived from the thread's last message;
header-threaded by an explicit `in_reply_to` / `references`
(`--in-reply-to` / `--references` on `oauth-draft-create`) when the
message is not in the user's Gmail but its `Message-ID` is known from
PonyMail or the tracker's recorded root; or, failing both, matched by
subject. Explicit IDs must each be one `local@domain` token (angle
brackets optional, whitespace and CR / LF refused, so no header
injection), `References` defaults to `in_reply_to` alone and has it
appended when the chain omits it, explicit headers win over a
`thread_id`'s (the thread is then not read), and `no_reply_headers`
with `in_reply_to` is refused (#2051). The security import, sync and
invalidate reply steps pass the PonyMail / recorded `Message-ID` when no
Gmail thread exists.
- `tools/maildir/` — private-mail drafting to a local Maildir spool
(`maildir-draft-create`, plus the read-only `maildir-draft-find` for the
existing-draft check); an offline alternative to Gmail, selected per
Expand Down Expand Up @@ -417,7 +431,10 @@ by swapping the adapter, not the skill.
provider-agnostic, stdlib-only Python API for structured decisions,
`choice(prompt, options)`, `score(prompt, scale)`, and `noul(prompt)`.
The Jev provider connects to TypeSafe's API (`api.typesafe.ai/v1/systemone`,
model pinned to `jev-1.14.0`); the local provider connects to a
model pinned to `jev-1.14.0`), sending one typed question per call with
the prompt as `state`; `score` sends at most 10 numeric levels (the API's
cap) and maps the returned level back onto the requested scale. The local
provider connects to a
self-hosted OpenAI-compatible chat-completions endpoint such as Ollama,
llama.cpp, or vLLM. `MAGPIE_TYPED_DECISION_PROVIDER` selects `jev` or
`local`; when unset, the registry selects configured Jev or reports
Expand Down
36 changes: 22 additions & 14 deletions tools/spec-loop/specs/adoption-and-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,10 @@ acceptance:
- Writing the committed default-set block touches only
`extraKnownMarketplaces`, `enabledPlugins` and the derived `mcp__…`
entries of `permissions.allow` (the MCP tools the adopted families
call, from `skills/setup/family-mcp-allows.json`) in
call, from `skills/setup/family-mcp-allows.json`, which lists only
tools that read one named item or report state — a tool that sends,
posts, deletes, creates a draft, or searches a whole mailbox or list
stays behind the harness prompt) in
`.claude/settings.json`, preserves every other top-level key and an
existing `apache-magpie` marketplace definition, adds only the floor
members missing from an existing `enabledPlugins` and removes nothing,
Expand Down Expand Up @@ -238,7 +241,7 @@ committed version with drift detection.

## Where it lives

- Skill: `setup` (install, config, adopt/unadopt, verify, upgrade,
- Skill: `setup` (install, config, adopt/unadopt, verify, update,
override, reconcile — the one-time project-wide reconciliation sweep) at
`plugins/magpie-setup/skills/setup/`: one `SKILL.md` plus a sibling
detail file per sub-action (`install.md`, `config.md`, `adopt.md`,
Expand Down Expand Up @@ -390,7 +393,7 @@ committed version with drift detection.
`.apache-magpie.local.lock`'s `source_ref` / `fetched_commit`; on
`svn-zip` it compares `ref` with `source_ref`; a missing, empty or
malformed lock of either kind is reported as drift.
`upgrade`, `verify` and a re-install also resolve a `git-tag` pin
`update`, `verify` and a re-install also resolve a `git-tag` pin
upstream and compare it with the committed `commit` anchor: a moved
tag stops them with both commits named, as `skill-sources` does for a
trusted source; only a deliberate `bump-committed` re-pins.
Expand Down Expand Up @@ -435,7 +438,7 @@ committed version with drift detection.
project hook, `.grok/hooks/magpie-agent-guard.json`, derived from
`plugins/magpie-setup/templates/grok-agent-guard-hook.json` (only the
executable path changes, to the snapshot's `agent_guard/__init__.py`).
`install`, `upgrade` and `uninstall` touch only that file, surface a diff
`install`, `update` and `uninstall` touch only that file, surface a diff
before replacing or removing a hand-edited copy, leave every other
`.grok/hooks/*` file and `.grok/config.toml` alone, and never grant or
reset Grok's project-hook trust, which stays the operator's decision.
Expand Down Expand Up @@ -533,13 +536,17 @@ committed version with drift detection.
unresolved.
- **The isolated-setup warning is shown once per session, in adopted repos
only.** `magpie-setup`'s `SessionStart` hook warns while the machine has no
isolated setup (its stamp, or a sandbox enabled in the project's or the
user's `settings.json`; the home directory's `settings.local.json` is not loaded and does not count): optional for a trial, recommended for longer use, the
isolated setup (its stamp, or else the most specific explicit
`sandbox.enabled` among the project's `settings.local.json`, the project's
`settings.json` and the user's `settings.json`, as Claude Code resolves it,
so a `/sandbox` toggle-off in the project's `settings.local.json` overrides
a wider `true`; the home directory's `settings.local.json` is not loaded and
does not count): optional for a trial, recommended for longer use, the
consequences of running without it, and a warning against pointing skills
at untrusted content. A project opts out with `isolation_warning: off` in
the committed `.apache-magpie-overrides/project.md`, which `adopt` asks
about; a personal layer cannot opt out.
- **`upgrade` splits on adoption:** nothing repo-side when the project
- **`update` splits on adoption:** nothing repo-side when the project
has not adopted; `min_version` raised — never lowered — and staged
when it has.
- **An unrecognised sub-action is never guessed** (#1391). A first
Expand All @@ -548,8 +555,9 @@ committed version with drift detection.
distance one or two, or a prefix; every candidate when several qualify)
and the full sub-action list, then waits.
It runs a suggested sub-action only after the user confirms it, and
never falls back to `install`, because `upgrade`, `reconcile` and
`adopt` stage committed files.
never falls back to `install`, because `update`, `reconcile` and
`adopt` stage committed files. The old sub-action name `upgrade` is not
treated as unknown: it runs the `setup-upgrade` skill instead.
- **Stacked PRs only with write access** (#1430). The agent conventions
block `install` writes into an adopter's `AGENTS.md`, like this repo's own
`AGENTS.md`, tells agents how to open a series of dependent PRs.
Expand Down Expand Up @@ -590,7 +598,7 @@ committed version with drift detection.
- **`method: local` has nothing to drift** (#1414). The framework
checkout's self-adoption writes `method: local` with a `source:` key; the
checker's lock parser accepts that key and returns no project findings
for the method, and `upgrade` on it only refreshes the pre-flight
for the method, and `update` on it only refreshes the pre-flight
checker from the in-repo package and stops.
Each canonical `.agents/skills/magpie-<n>` link of a self-adopted checkout
targets the skill's real directory, `../../plugins/<family>/skills/<alias>`
Expand Down Expand Up @@ -668,7 +676,7 @@ committed version with drift detection.
nothing and asks first.
11. Version comparison is PEP 440: `0.10.0` satisfies a `0.9.0` floor, and
`0.2.0` satisfies a `0.2.0.dev202609110041` floor.
12. `upgrade` writes nothing to the repo when the project has not adopted,
12. `update` writes nothing to the repo when the project has not adopted,
and raises — never lowers — `min_version` when it has.
13. `verify` reports a missing lock and an ahead-of-floor machine as not
faults, and a shortfall as one.
Expand Down Expand Up @@ -790,7 +798,7 @@ committed version with drift detection.
`magpie-setup` plugin on a marketplace install, and
`<snapshot-dir>/tools/setup-preflight/src/setup_preflight/` (the same
files, through the mirror link) on a snapshot install. `config` states that it installed an executable, since it may
run unattended from a skill's pre-flight. `upgrade` skips the refresh
run unattended from a skill's pre-flight. `update` skips the refresh
when no copy exists rather than creating one; it moves a copy an
earlier version left in an adopted project's `.apache-magpie-local/`
or in the project's `.git/apache-magpie/` or `.svn/apache-magpie/`.
Expand Down Expand Up @@ -821,7 +829,7 @@ committed version with drift detection.
runs the update and never blocks the skill.
28. The memoised project verdict is keyed on the lock files, the plugin
listing, and the checker's own `core.py` and `lockfile.py`, so a
checker refreshed by `upgrade` never serves the previous code's
checker refreshed by `update` never serves the previous code's
answer (#1414). A `method: local` lock, `source:` key included,
parses and yields no project findings.
29. An unrecognised `setup` sub-action is answered with close-match
Expand Down Expand Up @@ -897,7 +905,7 @@ committed version with drift detection.
`welcome enable` (the `setup-welcome-guide` skill). The guide never
blocks the requested work, is skipped where there is no personal layer,
and a layer holding only that record does not count as configured.
Checker verification during `config` and `upgrade` uses `--no-welcome`;
Checker verification during `config` and `update` uses `--no-welcome`;
unreadable optional guides do not suppress actual setup findings, and
guide names cannot select Markdown files outside the shipped guides.
The setup family runs no shared pre-flight, so the `setup` skill alone
Expand Down
17 changes: 11 additions & 6 deletions tools/spec-loop/specs/agent-isolation-sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -691,12 +691,17 @@ The reference model is four layers, layered:

The **allow** half ships too (#1393). `setup-isolated-setup-install`
carries the reference `permissions.allow` set into an adopter's
settings merge alongside `deny` and `ask` — `gh` reads, both
vetted-ops read forms, the read-only archive / mailbox / roster MCP
tools, and the registry `WebFetch` hosts (`cveawg.mitre.org`,
`pypi.org`, `lists.apache.org`) — and `setup-isolated-setup-update`
diffs it, because a missing read-only entry is a prompt on every skill
run. Only read-only entries belong there; `vetted-op` (writes) stays
settings merge alongside `deny` and `ask` — `gh` reads (with
`gh auth status` allowed only as the bare command, so a call with
flags prompts, #2019), both vetted-ops read forms, the archive and
mailbox MCP tools that read one named thread, message or draft or
report auth state, the roster MCP tools, and the registry `WebFetch`
hosts (`cveawg.mitre.org`, `pypi.org`, `lists.apache.org`) — and
`setup-isolated-setup-update` diffs it, because a missing read-only
entry is a prompt on every skill run. Whole-mailbox and whole-list
searches and draft creation (`mcp__gmail-plaintext__create_draft`)
stay off it, so those calls reach the operator as a prompt (#2020).
Only read-only entries belong there; `vetted-op` (writes) stays
on `ask`.
Install Step V now describes three entry points over one catalogue and
adds `vetted-op-tracker` and `vetted-op` to both `ask` and
Expand Down
2 changes: 1 addition & 1 deletion tools/spec-loop/specs/codex-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ acceptance:
remain subject to Codex approvals; hook trust is reviewed separately.
- Fixed installed vetted-op-read prefixes allow reads; both write entry
points prompt, with per-machine native rules rendered for review.
- Adopt, upgrade, verify, and unadopt account for the committed Codex
- Adopt, update, verify, and unadopt account for the committed Codex
policy.
- setup-isolated install, verify, update, and doctor route to explicit
Codex steps before any Claude-only procedure.
Expand Down
5 changes: 4 additions & 1 deletion tools/spec-loop/specs/contributor-growth.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,10 @@ Adopter config scaffolds live in `plugins/magpie-setup/templates/`
last `screen_recent_activity_months`), measures everyone
who remains — deliberately more than the PMC would consider,
alphabetically by handle, never scored, ranked, shortlisted or judged —
and writes a report (the list linked to details, plus a
and writes a report (a Headline split into committer and
`<governance-body>` lists, each alphabetical and linked to details with
one phrase restating the opening claim of that person's section, and
`None.` under a target with nobody measured; then a
one-or-two-paragraph summary of findings) with activity data, areas, community signals and verified
real names, each person's section opening with links to live code-host
searches of their full activity in the window; commits it only to a repository the GitHub API reports as
Expand Down
8 changes: 6 additions & 2 deletions tools/spec-loop/specs/issue-management-family.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,12 @@ unchanged.
+ `experimental`.

- Family README: `docs/issue-management/README.md` — family overview,
mode boundary with `pr-management-*` and `security-issue-*`, and the
adopter-config scaffold.
mode boundary with `pr-management-*` and `security-issue-*`, and a link
to the adopter scaffold index. Its install page,
`docs/issue-management/install.md` (*Install & first runs*), carries the
`/plugin install` line, the generated *Before the first run* config table
and *Try these first*; `tools/dev/check-doc-sync.py` requires that page
for every live family.

- Adopter config (templates in `plugins/magpie-setup/templates/`, which
`projects/_template/` links to): `project.md`,
Expand Down
5 changes: 4 additions & 1 deletion tools/spec-loop/specs/marketplace-distribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,10 @@ adopter-facing page.
`claude plugin update` nor auto-update runs anything in the adopter's
repo; each skill's pre-flight self-checks against the last reconciliation
on its first run after an upgrade, and `/magpie-setup:setup reconcile`
forces the full pass (`docs/setup/marketplace.md`, #1392). On machines
forces the full pass (`docs/setup/marketplace.md`, #1392). Until
`/magpie-setup:upgrade` has run and recorded the new version, every skill's
pre-flight also asks whether to upgrade now (`upgrade-pending`, #2041; see
[`adoption-and-setup.md`](adoption-and-setup.md)). On machines
using the isolated setup, the same pre-flight also proposes
`setup-isolated-setup-update` when the upgrade moved the secure-setup
fingerprint (see [`adoption-and-setup.md`](adoption-and-setup.md),
Expand Down
22 changes: 15 additions & 7 deletions tools/spec-loop/specs/pr-management-family.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,10 @@ same directory; the behaviour is unchanged.
rules in `tools/pr-management` (`mentor assess|render|tone-check|log`,
`reviewer-routing preflight|propose`, `pre-first-pr check|report`); their
detail files are per-classification under `classifications/`.
- Family README: `docs/pr-management/README.md` — family overview, skill
table, adopter-config scaffold.
- Family README: `docs/pr-management/README.md` — family overview and skill
table; `docs/pr-management/install.md` (*Install & first runs*) — the
`/plugin install` line, the generated *Before the first run* config table,
*Works well with* and *Try these first*.
- Tool: `tools/pr-management/` (`pr_management.stats`) — deterministic Python backing for
`pr-management-stats`; ships its own tests.
- Adopter config (templates in `plugins/magpie-setup/templates/`, which
Expand Down Expand Up @@ -296,7 +298,7 @@ same directory; the behaviour is unchanged.
7-day notice), and reuses triage's maintainer-court, ready-label, security
and bot rules; the close notice carries `<!-- pr-stale-sweep-close -->`.
Regression cases: `tools/pr-management/tests/stale_sweep/`.
- **Quick-merge never merges.** `pr-management-merge-candidates` surfaces
- **Merge-candidates never merges.** `pr-management-merge-candidates` surfaces
candidates and the maintainer runs the exact `gh pr merge` command
themselves. Automated merge belongs to a future Auto-merge mode that is
deliberately off by MISSION sequencing.
Expand Down Expand Up @@ -359,6 +361,9 @@ same directory; the behaviour is unchanged.
GitHub holds the merge until the required checks pass, but only when every
running check is a required one; a running check that is not required keeps
the gate, since auto-merge would not wait for it.
Its `ci_action` says to wait for those checks, or to approve their held
runs through `pr-management-triage`, because `release-runs` needs the
approval this gate withholds (#2029).
With CI held this way (`ci_pending_held_by_auto_merge`) plain `APPROVE` and
`FIXUP` are not offered, because without auto-merge they would approve on
unfinished CI.
Expand Down Expand Up @@ -434,11 +439,14 @@ same directory; the behaviour is unchanged.
The tool path — `with-reviewers:codex,copilot`, or a resolved
`adversarial-review.md` whose `mode` is not `off` — has the agent run the
[adversarial-review](adversarial-review.md) tool over `--target pr:<N>`
with `--repo-dir` set to a new temporary directory holding a `git archive`
export of the PR's head, made per PR, because the maintainer's own checkout
with `--repo-dir` set to a new temporary directory holding an export of
the PR's head, made per PR, because the maintainer's own checkout
must not be readable by other models and with an empty directory the
reviewers reply without findings (#1986).
The export excludes `.apache-magpie-overrides/tools/vetted-ops`, which the
The export goes through a temporary index (`git read-tree` plus
`git checkout-index`), not `git archive`, so paths marked `export-ignore`
stay in it (#2030).
It drops `.apache-magpie-overrides/tools/vetted-ops`, which the
secure setup denies writes to, so the agent reviews a PR's policy change
itself.
Its findings fold into the Step 4 list, attributed per reviewer, as
Expand Down Expand Up @@ -564,7 +572,7 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid

- **`experimental` — no adopter pilot has run the full family end-to-end.**
All nine skills are on main with eval suites; no maintainer has exercised
the triage → stats → code-review → quick-merge → mentor pipeline
the triage → stats → code-review → merge-candidates → thread-mentor pipeline
end-to-end under evaluation conditions. Shape may change as pilot
evaluations surface real-world usage patterns.
<!-- gap-closes-when: none (narrative) -->
Expand Down
5 changes: 3 additions & 2 deletions tools/spec-loop/specs/project-agnosticism.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,8 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid
the same h2 section headings. The live tree produces no `template-drift`
violations.
- **Example-only project names remain in skill bodies.** A case-insensitive
search finds 40 `airflow` mentions under `plugins/magpie-*/skills/`, almost
search finds 32 `airflow` mentions under `plugins/magpie-*/skills/`, almost
all `e.g.` examples or illustrative path globs (for instance the
`quick-merge` candidate-rules example); `check-placeholders.sh` guards the
`merge-candidates` example path in `actions/present.md`); `check-placeholders.sh` guards the
operational forms, and the remaining mentions are judged by a human.
<!-- gap-closes-when: none (narrative) -->
4 changes: 3 additions & 1 deletion tools/spec-loop/specs/repo-health-family.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,9 @@ grouped, prioritised report → wait for confirmation before any write.
Step 1. The GitHub Actions Policy, `.asf.yaml` and `creation_cap` checks
run only when `project.md` declares `organization: ASF`.
- Design docs: `docs/repo-health/README.md` — family overview and the
adopter-config scaffold.
adopter contract; `docs/repo-health/install.md` (*Install & first runs*)
— the `/plugin install` line, the generated *Before the first run* config
table, *Works well with* and *Try these first*.
- Adopter config: `plugins/magpie-setup/templates/repo-health-config.md`
(shipped inside the `magpie-setup` plugin) —
per-skill switches (deprecated-runner families, zizmor rule classes,
Expand Down
Loading