docs: add <framework> placeholder; update Python invocations to use it by potiuk · Pull Request #3 · apache/magpie

potiuk · 2026-04-28T21:29:53Z

Summary

PR 2 ported the generate-cve-json Python implementation into the framework. Skills currently invoke it via uv run --project tools/vulnogram/generate-cve-json … — works in framework standalone (cwd=repo root), but not in adopting projects, where the framework lives at the .apache-steward/apache-steward/ submodule path.

This PR introduces a <framework> placeholder. Adopting projects substitute it to .apache-steward/apache-steward/; framework-standalone substitutes to .. Skills now reference <framework>/tools/vulnogram/generate-cve-json everywhere they invoke the tool, and the path resolves in either context after the agent's standard placeholder substitution.

Files updated

AGENTS.md — new row in the placeholder-convention table for <framework>.
.claude/skills/{sync-security-issue,allocate-cve,deduplicate-security-issue}/SKILL.md — 6 invocation sites updated.
tools/vulnogram/generate-cve-json/SKILL.md — 3 invocation sites updated.
tools/vulnogram/generate-cve-json/README.md — documented the dual-context invocation with the placeholder.

Files NOT changed

Markdown links to SKILL.md (e.g. [generate-cve-json](../../../tools/vulnogram/generate-cve-json/SKILL.md)) — those work via the .claude/skills/ symlink in adopters because the kernel follows the symlink to the file's actual location and resolves the relative path from there.

Test plan

✅ Pre-commit passes (ruff/mypy/pytest + standard hooks).
✅ All 100 tests in the generate-cve-json package pass.
Future: dogfood a sync run in airflow-s once this lands and the submodule is bumped.

Coordination

This is the framework-side counterpart to airflow-s/airflow-s#363 (delete-local-cve-json-after-port). After this PR lands, airflow-s PR 3 needs one more commit to bump the submodule pointer to this PR's merge SHA — only then do skills work end-to-end on airflow-s.

🤖 Generated with Claude Code

After PR 2 ported the generate-cve-json Python implementation into the framework, skill files invoke it from the path `tools/vulnogram/generate-cve-json` — which resolves correctly in framework standalone (where `cwd` is the repo root) but not in adopting projects (where the framework is at the `.apache-steward/apache-steward/` submodule path and `tools/` is nowhere near `cwd`). This commit introduces a `<framework>` placeholder that resolves to: - `.apache-steward/apache-steward/` in adopting projects (the submodule path); - `.` (the repo root) in framework standalone. Skills now reference `uv run --project <framework>/tools/vulnogram/ generate-cve-json …`, which works in both contexts after the agent's standard placeholder substitution. Files updated: - AGENTS.md — added a new row to the placeholder convention table for `<framework>`. - .claude/skills/{sync-security-issue,allocate-cve,deduplicate- security-issue}/SKILL.md — 6 invocation sites updated. - tools/vulnogram/generate-cve-json/SKILL.md — 3 invocation sites updated; preamble note already in place from PR 2 calling out the config-driven design. - tools/vulnogram/generate-cve-json/README.md — documented the dual-context invocation pattern with the placeholder. Markdown LINKS to SKILL.md (e.g. `[generate-cve-json](../../../tools/ vulnogram/generate-cve-json/SKILL.md)`) are deliberately not rewritten — those work via the .claude/skills/ symlink in adopters because the kernel follows the symlink to the actual file location and resolves the relative path from there. Test plan: - Pre-commit (`prek run --all-files`) passes after the changes. - All 100 tests in the generate-cve-json package pass against the test fixture config. This is the framework-side counterpart to airflow-s PR 3 (delete-local-cve-json-after-port). After this lands and gets merged, the airflow-s PR 3 needs a final commit to bump the submodule pointer to this commit's SHA so adopting projects pick up both PR 2 (the Python implementation) and this PR's skill text. Generated-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Fifth and final PR of the security genericization series. Lifts the remaining 4 docs in docs/security/ to read config knobs from projects/_template/project.md and the contract docs from PR1-PR4 (cve_authority.*, governance.*, security_inbox.*, forwarders.*, archive_system.*, scope_detection.*). Plus a final scrub of 4 skills for leftover ASF/Vulnogram literals. Byte-equivalent for the airflow-s adopter: every ASF/Airflow/ Vulnogram-specific value either resolves through a config knob whose ASF default matches today's behaviour, OR stays as one named-example aside in generic prose. Per-target lifts: - docs/security/threat-model.md (+107/-77) — Purpose/Scope/ Assumptions reframed from "ASF"/"PMC" to governance-knob terms. STRIDE matrix rows A.6/A.7/C.1-C.4/E.1-E.2 lifted: Vulnogram -> <cve-tool>; security@apache.org -> <security-list>; DRAFT/REVIEW/READY/PUBLIC -> cve_authority.states sequence (allocated -> review-ready -> publish-ready -> public). Mitigations M.10/M.16/M.18/M.19/M.27 + residual risks #3/#8/#10/#11 + re-audit cadence ownership generalised. - docs/security/forwarder-routing-policy.md (+42/-27) — references the optional security-issue-import-via-forwarder sub-skill from PR3 (#387) and the tools/forwarder-relay/README.md contract. Replaces "ASF-security relay" / "security@apache.org" with forwarders.enabled / <security-list> / foundation_security_address. ASF-Airflow shown as a named-example aside per concept. - docs/security/how-to-fix-a-security-issue.md (+20/-8) — "governance-authorised member of the adopting project (per governance.cve_allocation_gate)" replaces "PMC member of apache/airflow"; <cve-tool> + cve_authority.* replaces Vulnogram- specific URLs and state names; archive_system.advisory_publication_signal_url replaces the lists.apache.org users-list URL. - docs/security/new-members-onboarding.md (+26/-13) — onboarding- style register preserved. "PMC members and committers" reframed as "governance body that satisfies governance.cve_allocation_gate"; per-user-config "PMC status" steps reference the governance knob; Vulnogram steps reference <cve-tool> via cve_authority.record_url_template. - Final scrub of 4 skills (+17/-15 net): security-issue-import, security-issue-import-via-forwarder, security-issue-invalidate, security-issue-fix — leftover literal references caught and lifted to roster.bare_name_handles / governance.escalation_contact / forwarders.<adapter>.contact_handle. Aggregate: 8 files, +240/-156 lines. That closes the series. Five PRs (#381, #386, #387, #388, this) transitioned the security skill family from Airflow/ASF-coupled to a generic framework with ASF as the default-configured option. The airflow-s adopter, with the ASF defaults baked into project.md, sees byte-equivalent behaviour throughout. Non-ASF adopters override specific dimensions (CVE authority, mail provider, archive system, governance gate, scope axis) by changing only their <project-config>/ files. Generated-by: Claude Code (Opus 4.7)

…erns from session manual cleanups (#402) Per direct observations from the airflow-s 2026-05-29/30 bulk sync — two recurring title-noise patterns were cleaned manually that the existing cascade did not catch: 1. Trailing prior-CVE-relationship parentheticals — the cross-CVE relationship is structurally captured by the Gate #3 cross-CVE clause in the public summary; embedding the relationship in the title is noise to downstream advisory consumers. Catches every shape observed in this session: - `(CVE-YYYY-NNNNN)` - `(possible CVE-YYYY-NNNNN variant)` — from #345 - `(incomplete fix for CVE-YYYY-NNNNN)` — from #351 - `(fix-bypass of CVE-YYYY-NNNNN)` — from #352 - and any other `(... CVE-YYYY-NNNNN ...)` shape 2. Trailing reporter-name attribution parentheticals — reporter attribution lives in the credits field, never in the public title. Pattern matches `(<name> follow-up)` where `<name>` matches name-like tokens (word chars, dots, hyphens, single inline spaces) to avoid over-stripping substantive technical content. Catches: - `(Evan Ricafort follow-up)` — from #346 Substantive technical parentheticals stay intact — e.g. the operator- name list `(GCSToSFTPOperator + GCSTimeSpanFileTransformOperator)` on the GCS path-traversal tracker is NOT stripped (it lacks a CVE ID and doesn't end in `follow-up`). The matching Step 1d signal row in security-issue-sync now enumerates the two new patterns so the proposal-time detector and the pre-push Gate #4 stay in lock-step with the cascade. Validated against 9 cases: 4 session-derived fixes (all pass), 3 synthetic CVE-relationship variants (all pass), 1 substantive technical parenthetical (preserved correctly), 1 "<word> follow-up" edge case (stripped as designed — narrow scope acceptable since "follow-up" titles in airflow-s are exclusively reporter-attribution). Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

potiuk merged commit 86036ca into main Apr 28, 2026

andreahlert added the mode:platform Substrate / infra — not a mode (sandbox, CI, validators) label May 7, 2026

andreahlert mentioned this pull request May 7, 2026

docs(security): add release-blocking threat model #91

Merged

6 tasks

This was referenced May 29, 2026

feat(security-issue-sync): five pre-push hygiene gates for CVE-record quality #372

Merged

feat(generate-cve-json): emit related references for sibling CVEs #384

Merged

feat(security): docs lift + final scrub (PR5/5) #399

Merged

potiuk mentioned this pull request May 30, 2026

feat(security-cve-allocate): extend title-strip cascade with patterns from session cleanups #402

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add <framework> placeholder; update Python invocations to use it#3

docs: add <framework> placeholder; update Python invocations to use it#3
potiuk merged 1 commit into
mainfrom
skills-framework-placeholder

potiuk commented Apr 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

potiuk commented Apr 28, 2026

Summary

Files updated

Files NOT changed

Test plan

Coordination

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants