diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync index 31485b9f7..b6a848934 100644 --- a/tools/spec-loop/.last-sync +++ b/tools/spec-loop/.last-sync @@ -1 +1 @@ -1e5c4f9110812f1c0bc4bc6312723c9f98c82fca +bfc99bb6f47be727b124adf939e5c010fe33ba5f diff --git a/tools/spec-loop/specs/adapters.md b/tools/spec-loop/specs/adapters.md index 8cc355028..782462586 100644 --- a/tools/spec-loop/specs/adapters.md +++ b/tools/spec-loop/specs/adapters.md @@ -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 @@ -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 diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md index a4913d077..f5dc1a7fe 100644 --- a/tools/spec-loop/specs/adoption-and-setup.md +++ b/tools/spec-loop/specs/adoption-and-setup.md @@ -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, @@ -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`, @@ -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. @@ -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. @@ -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 @@ -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. @@ -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-` link of a self-adopted checkout targets the skill's real directory, `../../plugins//skills/` @@ -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. @@ -790,7 +798,7 @@ committed version with drift detection. `magpie-setup` plugin on a marketplace install, and `/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/`. @@ -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 @@ -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 diff --git a/tools/spec-loop/specs/agent-isolation-sandbox.md b/tools/spec-loop/specs/agent-isolation-sandbox.md index e8c57a4af..7ea274680 100644 --- a/tools/spec-loop/specs/agent-isolation-sandbox.md +++ b/tools/spec-loop/specs/agent-isolation-sandbox.md @@ -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 diff --git a/tools/spec-loop/specs/codex-runtime.md b/tools/spec-loop/specs/codex-runtime.md index abad63036..5475b7a9e 100644 --- a/tools/spec-loop/specs/codex-runtime.md +++ b/tools/spec-loop/specs/codex-runtime.md @@ -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. diff --git a/tools/spec-loop/specs/contributor-growth.md b/tools/spec-loop/specs/contributor-growth.md index df4dce364..7757eb70b 100644 --- a/tools/spec-loop/specs/contributor-growth.md +++ b/tools/spec-loop/specs/contributor-growth.md @@ -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 + `` 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 diff --git a/tools/spec-loop/specs/issue-management-family.md b/tools/spec-loop/specs/issue-management-family.md index e629774e4..dec8ce785 100644 --- a/tools/spec-loop/specs/issue-management-family.md +++ b/tools/spec-loop/specs/issue-management-family.md @@ -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`, diff --git a/tools/spec-loop/specs/marketplace-distribution.md b/tools/spec-loop/specs/marketplace-distribution.md index 22090a6ee..12b41d148 100644 --- a/tools/spec-loop/specs/marketplace-distribution.md +++ b/tools/spec-loop/specs/marketplace-distribution.md @@ -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), diff --git a/tools/spec-loop/specs/pr-management-family.md b/tools/spec-loop/specs/pr-management-family.md index d57699425..1af3297f7 100644 --- a/tools/spec-loop/specs/pr-management-family.md +++ b/tools/spec-loop/specs/pr-management-family.md @@ -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 @@ -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 ``. 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. @@ -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. @@ -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:` - 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 @@ -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. diff --git a/tools/spec-loop/specs/project-agnosticism.md b/tools/spec-loop/specs/project-agnosticism.md index 5f03b48d0..bdff025ba 100644 --- a/tools/spec-loop/specs/project-agnosticism.md +++ b/tools/spec-loop/specs/project-agnosticism.md @@ -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. + diff --git a/tools/spec-loop/specs/repo-health-family.md b/tools/spec-loop/specs/repo-health-family.md index 3286e03aa..12eb6f92c 100644 --- a/tools/spec-loop/specs/repo-health-family.md +++ b/tools/spec-loop/specs/repo-health-family.md @@ -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, diff --git a/tools/spec-loop/specs/security-issue-lifecycle.md b/tools/spec-loop/specs/security-issue-lifecycle.md index e8a54fac3..fba2d73e8 100644 --- a/tools/spec-loop/specs/security-issue-lifecycle.md +++ b/tools/spec-loop/specs/security-issue-lifecycle.md @@ -94,8 +94,9 @@ publication, with a human gate and an audit-log entry at every step. disclosure-governance defaults, the Step 1 pre-filter, the Step 2 `threadId` batches and their attribution, the Step 3 forwarder pre-screen, the Step 6 reply grammar and the Step 7 receipt-draft - matrix, and renders the tracker body (the report as an inert fenced - block, `_No response_` for empty fields, headings from + matrix, and renders the tracker body (the report as defanged markdown + under a fixed `> [!NOTE]` data marker, or an inert fenced block with + `description_format: inert`, `_No response_` for empty fields, headings from `tracker.body_fields`), the rollup entry, the rejections-ledger record, the fix-already-public reply and the Step 8 recap. Classification, field extraction, PII identification, @@ -111,7 +112,8 @@ publication, with a human gate and an audit-log entry at every step. For `security-issue-import-from-md` it parses the findings file (`not-a-findings-file` on another shape, `UNKNOWN` severity and `` fallback with warnings), cleans the search keyword, and - renders the body (each section an inert block, the Recommended-fix + renders the body (each section defanged markdown, or an inert block + with `description_format: inert`, the Recommended-fix `
`), rollup entry, proposal table and recap; duplicate judgement and the credit decision stay with the model. For `security-issue-import-via-forwarder` it runs the Step 0 checks, @@ -318,20 +320,34 @@ publication, with a human gate and an audit-log entry at every step. Without the tool, or for a Gmail-only report, the proposal lists the names as not fetched; `get_source`, `get_mbox` and downloads are never used to recover one. -- **Report text is inert in the tracker (#1672).** The importers put - reporter-derived long text (the mail body, the PR description, each - findings-file section) into the body as one fenced block with info - string `text`, its fence one backtick longer than the longest backtick - run in the text. Nothing in it renders — no image, HTML, heading, link - or mention — and its content is byte-exact except two escapes: a line - that would end a field (`###` then a space, a tab or nothing, at column - 0 or behind `>`, list markers or indent, whatever the name), and a line - starting with `