diff --git a/tools/spec-loop/IMPLEMENTATION_PLAN.md b/tools/spec-loop/IMPLEMENTATION_PLAN.md index 4fab36d3..01389e95 100644 --- a/tools/spec-loop/IMPLEMENTATION_PLAN.md +++ b/tools/spec-loop/IMPLEMENTATION_PLAN.md @@ -7,39 +7,96 @@ Maintained by the loop's **plan** mode. It is the prioritised list of *gaps* found by comparing [`specs/`](specs/) against the actual code (`.claude/skills/`, `tools/`, `docs/`). The **build** mode takes the single highest-priority work item, isolates it on its own branch, -implements it, validates it, and commits — **one work item, one branch, -one PR** (the branch-per-feature constraint). +implements it, validates it, and commits: one work item, one branch, +one PR (the branch-per-feature constraint). > Priority lives here, not in the specs. The specs describe functional > areas (unordered); this plan orders the work. --- -Shipped state is not tracked here — it lives in `specs/`, the code +Shipped state is not tracked here. It lives in `specs/`, the code (`skills/`, `tools/`, `docs/`), and git history. This plan lists only the open gaps. Confirm whether something is already built by the artifact it would produce, not by branch ancestry (squash-merged branches still read as ahead of `main`). -## In-flight (implemented on a branch, not yet merged — not available to build) +*Last reconciled against `main` on 2026-07-12 (`main` at #829). Each +In-flight entry below was re-verified by checking its artifact against +`main`, not by branch ancestry.* -These work items are already built on branches (verified by the feature -commit, not by branch ancestry) but are not on `main`, so the working tree -and validator still show the gap. Keep them out of the build queue until they -merge or are abandoned. +## In-flight (implemented on a branch, not yet merged — not available to build) -| Branch slug | Where | Implemented by | Description | -|---|---|---|---| -| `modes-doc-reviewer-routing-row` | `origin` (open PR) | `9331fb2ba` | Adds the `reviewer-routing` row to the `## Triage` table in `docs/modes.md`. | -| `adapter-readme-authoring-compliance` | `origin` (open PR) | `b31732578` | Documents the missing adapter-authoring README fields (config-keys / operations). | -| `skill-reconciler-structural-diff` | local | `ae8961e90` | Adds the deterministic `tools/skill-reconciler-diff` structural-diff helper. | -| `skill-reconciler-source-pairing` | local | `a4f76e369` | Adds `--discover` capability-tag auto-pairing to `skill-reconciler`. | +Each item below is already built and lives on a local work-item branch; its +artifact is verified **absent from `main`** (or present but not yet carrying +the branch's change), so it is not shippable but must **not** be re-picked for +build. The loop's dedup consults open PRs and *local* work-item branches +(`refs/heads/`), so an item that was pushed to `origin` and then had its local +branch deleted is invisible to that check and will be rebuilt. This list is the +backstop. Drop each item once its branch merges to `main`. -The MISSION-named education pages (landing page, pattern catalogue, "your first -skill", eval-driven development, and the hands-on lab) have shipped to `main`. -The open education gap is now the **progression restructure** — sequencing those -pages into an ordered learning path and adding the new conceptual stages — which -is the single work item below. +- **`message-localization`** (`b890c38e9`, local branch only). New + `message-localization` skill that translates contributor-facing agent prose + with human sign-off, plus a two-step eval suite (detect-language, translate) + and `supported-languages.md`. Skill, wiring in `docs/modes.md` and + `docs/labels-and-capabilities.md`, and evals are all absent from `main`. + Spec: [`specs/mentoring-mode.md`](specs/mentoring-mode.md). +- **`pattern-catalogue-eval-layout-fix`** (`7c8801577`, local). Rewrites Pattern 8 + in `docs/education/pattern-catalogue.md` to the real `fixtures/` + + `step-config.json` + `case-*/` layout. `pattern-catalogue.md` is on `main`; + this correction is not. + Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). +- **`your-first-skill-step-renumber`** (`bfc3e1a63`, local). Adds the step-6 + Debugging-a-skill and step-7 Portable-skills entries to the "Where to go next" + list in `docs/education/your-first-skill.md` and renumbers the tail so the + progression reads 5 → 6 → 7 → 8. Both target pages are on `main`; these links + are not. + Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). +- **`local-smoke-candidate-sweep`** (`b656f4615`, local). Tags 64 small-model- + friendly `case-meta.json` cases across 20 skills with `local-smoke`. None of + the tag additions are on `main`. + Spec: [`specs/meta-and-quality-tooling.md`](specs/meta-and-quality-tooling.md). +- **`sandbox-lint-any-harness`** (`4306e0f97`, local). Adds a `--any-harness` + posture check to `sandbox-lint` and declares the tool harness-agnostic, moving + it into the harness-neutral bucket in `docs/vendor-neutrality.md`, plus posture + tests. `main` still lists `sandbox-lint` as `✅ portable` (Claude Code / Kiro / + OpenCode), so this slice is unmerged. + Spec: [`specs/agent-isolation-sandbox.md`](specs/agent-isolation-sandbox.md). +- **`permission-audit-any-harness`** (`4de6e5772`, local). Same harness-neutral + posture move for `permission-audit`: `--any` CLI mode, `docs/vendor-neutrality.md` + reclassification, and tests. `main` still lists `permission-audit` as + `✅ portable`, so this slice is unmerged. With `agent-isolation` (agnostic) and + `agent-guard` (exec-mode) already on `main`, these last two substrate tools are + the remainder of the harness-portability push. + Spec: [`specs/agent-isolation-sandbox.md`](specs/agent-isolation-sandbox.md). +- **`education-training-lesson-lab`** (`eee643377`, local). Remaining slice of the + Apache Training epic: adds `docs/education/training/lesson-lab-tutorials.md` and + wires it into `docs/education/training/README.md`. Lessons 01–11, the instructor + guide, and the README index are already on `main`; this hands-on lab page is not. + Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). +- **`education-training-upstream-contribution`** (`d746e3197`, local). Other + remaining Apache Training slice: adds + `docs/education/training/upstream-contribution.md`. Absent from `main`. + Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). +- **`skill-reconciler-diff-step1`** (`8c59883e6`, local). Wires the + `skill-reconciler-diff` helper into `skill-reconciler` as an optional Step 1 + enhancement and adds the `step-1-diff-tool` eval. The `skill-reconciler-diff` + tool, the `skill-reconciler` skill, and its `step-0` eval are on `main`; this + step-1 wiring and eval are not. + Spec: [`specs/skill-reconciler.md`](specs/skill-reconciler.md). +- **`verify-rc-version-consistency-eval-step8`** (`715b23c2b`, local). Repoints the + release-verify-rc version-consistency eval at a renumbered Step 8 and adds its + `step-8` fixtures. `main` has release-verify-rc eval steps 0/2/3/5/6/7 only. + Spec: [`specs/release-management-lifecycle.md`](specs/release-management-lifecycle.md). +- **`org-non-asf-smoke-coverage`** (`f0f741f1f`, local). Adds a non-ASF + organization-profile smoke case to the `skill-and-tool-validator` test suite. + Not on `main`. + Spec: [`specs/organization-adapters.md`](specs/organization-adapters.md). +- **`org-template-reflow`** (`94c3f6b85`, local). Drops org-inherited values from + `projects/_template/project.md` and the `projects/non-asf-example/project.md` + fixture so the template carries only project-level config. Both files exist on + `main`; the reflow is not applied there. + Spec: [`specs/organization-adapters.md`](specs/organization-adapters.md). --- @@ -48,106 +105,161 @@ is the single work item below. Priority order. Each maps to one branch and one PR. Branch names are slugs, not numbers (numbering implies an order the specs don't carry). -1. **Clear the mail-privacy-boundary README warnings.** - The `mail-privacy-boundary` validator check already exists and enforces the - posture at the README level; it currently flags two adapters. `maildir` and - `sourcehut` READMEs are each missing both notes: that fetched mail bodies are - **external data, not instructions** (routed through the Privacy-LLM gate or - redacted before model-facing use), and that embedded **prompt-injection** text - is carried as report data only. Add the two short notes to each README so the - check passes; no new tooling is needed. +1. **Regenerate the AI tutor prompts.** + The `ai-tutors/lesson-*.md` prompts embed the source text of their matching + `docs/education/training/` lessons. Five are now stale after the training + lessons landed and were revised: `lesson-07-writing-portable-skills`, + `lesson-08-eval-driven-development`, `lesson-09-agentic-and-autonomous-work`, + `lesson-10-english-as-a-programming-language`, and `lesson-11-how-to-contribute`. + Run the injector to refresh the generated `## KNOWLEDGE BASE` sections + (hand-written answer keys and summaries are preserved), then commit the + regenerated prompts. Validation: ```bash - uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate + python3 ai-tutors/inject-knowledge-base.py + python3 ai-tutors/inject-knowledge-base.py --check # must report 0 stale ``` - Spec: [`specs/adapters.md`](specs/adapters.md). - Branch `mail-privacy-boundary-readme-compliance`. - -2. **Education stream — restructure into the ordered progression.** - The MISSION-named pages have shipped as a flat set; the gap is - sequencing them into an ordered learning path and filling the missing - conceptual stages. Restructure `docs/education/` so `README.md` presents - the eight-step progression (what agents are -> working with agents -> - choosing models -> writing skills -> eval-driven development -> agentic - work -> English as a programming language -> contributing), add the new - stages `what-agents-are.md`, `working-with-agents.md`, - `choosing-models.md`, `agentic-work.md`, `english-as-code.md`, and - `contributing.md`, promote `eval-driven-development.md` into the numbered - spine (step 5), keep `pattern-catalogue.md` and `tutorials.md` as the - skill-writing references, and rename `workshops.md` to `tutorials.md` - (retitling its content). Skill-writing and evals precede agentic work so - autonomy is taught only after a skill is built and tested. Every - page keeps SPDX headers, project-agnostic placeholders (PRINCIPLE 12), - and Apache-2.0 licensing (PRINCIPLE 17), cross-links forward/back in the - progression, and passes doctoc / markdownlint / link checks. This is one - cohesive doc change (a single reviewable PR) rather than one-page-per- - branch, because the pages link to each other and a partial split would - break the link check mid-flight. + Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). + Branch `ai-tutors-regenerate`. + +2. **Make the AI tutors discoverable from the education docs.** + The tutors exist under `ai-tutors/` but the learner-facing docs barely point + to them, so a reader following the `docs/education/` progression never learns + they can be taught interactively. Add a short "Learn with an AI tutor" section + to `docs/education/README.md` and `docs/education/training/README.md` that says + what the tutors are, that each maps to one lesson, and how to load one (paste + everything below the `---` as the system prompt), linking to + [`ai-tutors/README.md`](../../ai-tutors/README.md) for the per-tool detail. + Confirm `ai-tutors/README.md`'s Files table lists all eleven lessons. Keep it + one cohesive doc change (one PR); no tutor content is regenerated here. Validation: ```bash - test -f docs/education/what-agents-are.md - test -f docs/education/working-with-agents.md - test -f docs/education/choosing-models.md - test -f docs/education/agentic-work.md - test -f docs/education/english-as-code.md - test -f docs/education/contributing.md - test -f docs/education/tutorials.md - test ! -f docs/education/workshops.md - grep -q "education" docs/index.md - uv run --project tools/spec-validator --group dev pytest - uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate + grep -qi "ai-tutor" docs/education/README.md + grep -qi "ai-tutor" docs/education/training/README.md ``` Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). - Branch `education-progression-restructure`. - -3. **Package the education stream as an Apache Training curriculum module.** - Building on the maintainer-education stream (work item 2), repackage the - `docs/education/` material as a reusable, LMS-neutral **Apache Training** - module so any project — ASF or not — can *teach* it, not just read it. Add - `docs/education/apache-training/` with per-lesson **learning objectives**, - hands-on **exercises**, and **self-check** questions, plus a module index - mapping each lesson back to its source page (the progression stages, the - pattern catalogue, eval-driven development, and the `tutorials.md` lab). - Shape the module to Apache Training conventions so it can be contributed - upstream there. Keep it project-agnostic (placeholders, PRINCIPLE 12) and - Apache-2.0 (PRINCIPLE 17). Blocked until the progression restructure (work - item 2) lands, since it repackages those pages. - **This is an epic, not a single PR.** It sits at the bottom by priority (not - dependency) and must be **decomposed into many work items before building** — - the loop's one-item-one-branch rule means no single branch should carry the - whole module. Likely split, each its own branch/PR when it reaches the top: - - one **lesson-module** item per source page (the progression stages, the - pattern catalogue, eval-driven development, the `tutorials.md` lab), each - carrying its learning objectives, content, and self-checks; - - a hands-on **exercise / fixture** item per lesson, reusing - `tools/skill-evals` fixtures where possible; - - an **instructor / facilitator guide** so any PMC (ASF or not) can teach the - module themselves; - - an **upstream-contribution** item coordinating the module shape and hand-off - with the Apache Training project. - The first build step when this reaches the top is a planning pass that - replaces this umbrella entry with the concrete sub-items above. - Validation (per sub-item, once decomposed): + Branch `ai-tutors-doc-discoverability`. + +3. **Add the `.apache-magpie-local/` personal override surface.** + Foundational for the hybrid-setup work below. Implement acceptance 5 of + [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md): a gitignored, + per-person override directory read at runtime as a sibling to the committed + `.apache-magpie-overrides/`, with precedence personal-local -> committed -> + organization -> framework default (first hit wins) and the same additive-only + guardrail (it cannot weaken the safety / confidentiality / privacy baseline). + Teach the override-reading path and `setup-status` about it, and have adoption + add the `.gitignore` entry. Document the `docs/setup/` agentic-overrides + contract to cover the new surface. + Validation: ```bash - uv run --project tools/spec-validator --group dev pytest uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate + grep -qi "apache-magpie-local" docs/setup/*.md ``` - Spec: [`specs/maintainer-education.md`](specs/maintainer-education.md). - Branches: per sub-item (decomposed before build); umbrella slug - `education-apache-training-module`. + Spec: [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md). + Branch `magpie-local-convention`. + +4. **Add a one-shot "use framework defaults this run" switch.** + Implement acceptance 6 of `specs/adoption-and-setup.md`: a per-invocation + switch that runs a skill against framework defaults for that session only, + ignoring both `.apache-magpie-local/` and `.apache-magpie-overrides/` without + editing or deleting either, with the safety baseline still applied. Smaller + than item 3 and independent of it in principle, but the override-reading path + it toggles is the same one item 3 extends, so land item 3 first. + Validation: + ```bash + uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate + ``` + Spec: [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md). + Branch `override-bypass-one-shot`. + +5. **How-to: use Magpie on a repo that has not adopted it.** (blocked on item 3) + A `docs/setup/` recipe for the "I am not on Project X, it has not adopted + Magpie, but I want to use Magpie for a fix" case: whole-user install, drop a + `.apache-magpie-local/`, add the one `.gitignore` line, run against the target + repo. Behaviour is already largely supported once item 3 lands; the gap is the + documented path. + Validation: + ```bash + test -f docs/setup/personal-use-unadopted-repo.md + ``` + Spec: [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md). + Branch `howto-personal-use-unadopted-repo`. + +6. **How-to: per-role MCP access (e.g. release manager enables a Policy MCP).** + (blocked on item 3) A `docs/setup/` recipe showing a member enabling a + capability or MCP server in their own `.apache-magpie-local/` while other + members leave it off, without changing shared project config. + Validation: + ```bash + test -f docs/setup/per-role-mcp-access.md + ``` + Spec: [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md), + [`specs/organization-adapters.md`](specs/organization-adapters.md). + Branch `howto-per-role-mcp`. + +7. **How-to: mixed-adoption teams (some use Magpie, some do not).** (blocked on + item 3) A `docs/setup/` recipe for one person running Magpie on a shared repo + via whole-user install plus `.apache-magpie-local/` without requiring teammates + to opt in. Fold in a small probe: confirm shared skills do not assume every + teammate has Magpie; if any skill hard-fails in that situation, file it as its + own gap rather than papering over it in the doc. + Validation: + ```bash + test -f docs/setup/mixed-adoption-teams.md + ``` + Spec: [`specs/adoption-and-setup.md`](specs/adoption-and-setup.md). + Branch `howto-mixed-adoption-teams`. + +Items 5–7 are blocked on item 3 (they document the surface it introduces). +Beyond the items above, every other gap from the previous plan has either shipped +to `main` or sits in the In-flight list above awaiting review and merge. Once the +In-flight items merge, run a fresh plan pass against `specs/` to surface the next +round of gaps. + +Shipped to `main` since the last plan and no longer tracked here (a partial, +plan-relevant list; git history is authoritative): + +- **Maintainer-education progression** restructured into the ordered path and the + new conceptual stages landed (`what-agents-are`, `working-with-agents`, + `choosing-models`, `agentic-work`, `english-as-code`, `contributing`, with + `pattern-catalogue` and `eval-driven-development` as references and + `workshops.md` renamed to `tutorials.md`). The `debugging-skills` (step 6) and + `portable-skills` (step 7) pages and `writing-safe-skills` (step 5) also landed. +- **Apache Training epic** largely shipped: `docs/education/training/` lessons + 01–11, the README index, and the instructor guide (#805–#811 and neighbours). + Only the lesson-lab and upstream-contribution pages remain In-flight. +- **Harness-portability substrate**: `agent-isolation` is now `✅ agnostic` + (`agent-iso` entry point) and `agent-guard` gained harness-neutral exec-mode. + `sandbox-lint` and `permission-audit` are the two remaining substrate slices + (In-flight above). +- **`no-telemetry-import`** SOFT validator check plus the PRINCIPLE 10 guarantee + note on `egress-gateway`. +- **`skill-reconciler`** skill and the `skill-reconciler-diff` tool with a + `step-0` eval; **`skill-md-line-limit-check`** SOFT advisory; the + `dependency-license-audit` skill (#814). +- Broad release, bitbucket, security-issue-sync, and setup/adoption work through + #829 (clean source-only RC tarball, read-only bitbucket PR fetches, frontmatter + family/mode/when_to_use requirement, Meta mode, and more). --- ## Notes & discoveries -- `git push` and `gh pr create` are intentionally **not** run by the loop — - they are in the repo's `ask` permission list and are the human's step. +- `git push` and `gh pr create` are intentionally **not** run by the loop. + They are in the repo's `ask` permission list and are the human's step. +- Because the loop never pushes, its "already built" dedup checks open PRs and + *local* work-item branches only. An item that a human has pushed to `origin` + (and whose local branch was then deleted) is invisible to that check and will + be rebuilt unless it is listed in **In-flight** above. Keep that list current. +- Stale plan-mode branches exist locally (`plan-0705`, `plan-0706`, `plan-0712`). + They are prior snapshots of this file, not build items; `plan-0712` is identical + to `main`. The canonical plan is this file on `main`. - Validation per work item lives in the relevant spec's **Validation** section; the build prompt runs it as backpressure before committing. When a build creates a new skill, its eval suite is part of that same work item. -- Agentic Autonomous is deliberately off and has no work items — building toward +- Agentic Autonomous is deliberately off and has no work items. Building toward it would skip the proof MISSION requires. - Deferred by design (not build items): Agentic Triage contributor-growth gaps (PMC-member nomination, emeritus handling, offboarding) and the remaining - low-confidence ASF-coupling advisories — both stay human-judgement until a + low-confidence ASF-coupling advisories. Both stay human-judgement until a spec turns them into a rule. diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md index c05f093a..443d1a6c 100644 --- a/tools/spec-loop/specs/adoption-and-setup.md +++ b/tools/spec-loop/specs/adoption-and-setup.md @@ -17,6 +17,10 @@ acceptance: re-installs the same framework version. - Drift between the committed pin and the local install is detected and surfaced with an upgrade proposal. + - A gitignored `.apache-magpie-local/` supplies per-person overrides that + layer above the committed `.apache-magpie-overrides/`, cannot weaken the + safety baseline, and can be ignored for a single run via a one-shot + default switch. --- # Adoption & setup @@ -67,6 +71,23 @@ gitignored skill symlinks, and committed agent-readable override files. privacy, or external-content-as-data baseline. If an override conflicts with those baseline rules, the framework rule wins and the conflict is surfaced. +- **Personal, gitignored overrides** live under `.apache-magpie-local/`, a + per-person sibling to the committed `.apache-magpie-overrides/` that is + never committed. It is read at runtime under the same additive-only + guardrail as any override: it may carry a person's paths, wording, or + capability/MCP enablement (for example a release manager enabling a + Policy MCP that other members leave off), but it cannot weaken the safety, + confidentiality, or privacy baseline. Precedence, first hit wins: + `.apache-magpie-local/` -> `.apache-magpie-overrides/` -> organization + defaults -> framework default. Adoption adds the `.gitignore` entry; on a + repo that has not adopted Magpie, the user adds that one line by hand so + the directory stays untracked. This is the surface that makes hybrid + setups work: one person can run Magpie against a shared or non-adopting + repo without committing anything or requiring teammates to opt in. +- **One-shot default run.** A per-invocation switch runs a skill against + framework defaults for that session only, ignoring both + `.apache-magpie-local/` and `.apache-magpie-overrides/`, without editing or + removing either file. The safety baseline still applies. ## Out of scope @@ -82,6 +103,14 @@ gitignored skill symlinks, and committed agent-readable override files. 4. Override files can be discovered and surfaced to skills without editing upstream skill bodies, and override text cannot weaken the safety/confidentiality baseline. +5. A gitignored `.apache-magpie-local/` is read as a per-person override + surface that layers above `.apache-magpie-overrides/` (personal-local -> + committed -> organization -> framework default, first hit wins), under the + same additive-only guardrail, and works on a repo that has not adopted + Magpie once its `.gitignore` line is present. +6. A one-shot switch runs a skill against framework defaults for a single + session, ignoring both override surfaces without deleting them, and the + safety baseline still applies. ## Validation @@ -95,3 +124,9 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid - `stable`; gaps appear as new agent targets to add to the registry ([`agents.md`](../../../skills/setup/agents.md)) or new override surfaces — recorded by the plan pass. +- **Not yet built:** the `.apache-magpie-local/` personal override surface + (acceptance 5) and the one-shot default-run switch (acceptance 6). Both are + intended behaviour recorded here and tracked as work items + `magpie-local-convention` and `override-bypass-one-shot` in the plan. The + three hybrid-setup how-tos that build on the local surface are tracked + alongside them.