(airflow-steward) 01/01: docs: add placeholder; update Python invocations to use it

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch skills-framework-placeholder
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git

commit 2ac38726e21471f5e8ef3ec9c6fa464a0742001d
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Tue Apr 28 23:28:27 2026 +0200

    docs: add <framework> placeholder; update Python invocations to use it
    
    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) <no...@anthropic.com>
---
 .claude/skills/allocate-cve/SKILL.md               |  6 +++---
 .claude/skills/deduplicate-security-issue/SKILL.md |  2 +-
 .claude/skills/sync-security-issue/SKILL.md        |  4 ++--
 AGENTS.md                                          |  1 +
 tools/vulnogram/generate-cve-json/README.md        | 20 +++++++++++++++++---
 tools/vulnogram/generate-cve-json/SKILL.md         |  6 +++---
 6 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/allocate-cve/SKILL.md b/.claude/skills/allocate-cve/SKILL.md
index b6c6c6d..402188a 100644
--- a/.claude/skills/allocate-cve/SKILL.md
+++ b/.claude/skills/allocate-cve/SKILL.md
@@ -369,7 +369,7 @@ user to confirm. Numbered items:
 4. **Regenerate the CVE JSON attachment** in the tracker body by
    running
    ```bash
-   uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
+   uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
    ```
    This is how the CVE record first gets seeded with the allocated
    ID. The remediation-developer credit (if any) comes from the
@@ -440,7 +440,7 @@ spaces inside the block, one blank line after
 
 Allocated via the ASF Vulnogram form at <https://cveprocess.apache.org/allocatecve>; the CVE ID is now the canonical reference in every downstream artifact (CVE JSON, advisory email, credit lines, cross-links). Scope `<scope label>` → product `<product>` → `packageName` `<packageName>`.
 
-Vulnogram paste-ready JSON was regenerated from the current body state (CWE `<CWE>`, severity `<severity>`, affected `<affected versions>`, `<N>` credits, `<N>` references) and embedded in the issue body. Re-run `uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> --attach` after any body change to keep the JSON in sync.
+Vulnogram paste-ready JSON was regenerated from the current body state (CWE `<CWE>`, severity `<severity>`, affected `<affected versions>`, `<N>` credits, `<N>` references) and embedded in the issue body. Re-run `uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> --attach` after any body change to keep the JSON in sync.
 
 </details>
 ```
@@ -488,7 +488,7 @@ partial failures stay legible:
    repos/<tracker>/issues/comments/<id> --input …`), or create
    the rollup (`gh issue comment <N> --repo <tracker>
    --body-file <tmp>`) if none exists yet.
-4. `uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> --attach`
+4. `uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> --attach`
    — embeds the CVE JSON in the body.
 5. Create draft on the original thread (reporter notification, if
    applicable) via the project's configured drafting backend — see
diff --git a/.claude/skills/deduplicate-security-issue/SKILL.md b/.claude/skills/deduplicate-security-issue/SKILL.md
index bce58ec..8fea886 100644
--- a/.claude/skills/deduplicate-security-issue/SKILL.md
+++ b/.claude/skills/deduplicate-security-issue/SKILL.md
@@ -396,7 +396,7 @@ After confirmation, apply **sequentially** (never in parallel):
    (GitHub's `duplicate` close-reason is not exposed by `gh` on
    all versions; `not planned` combined with the `duplicate` label
    carries the same signal)
-6. `uv run --project tools/vulnogram/generate-cve-json generate-cve-json <keep> --attach`
+6. `uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <keep> --attach`
    — the *Remediation developer* body field is the source of truth
    for remediation-developer credits (populated by the
    `sync-security-issue` skill from the linked PR's author); no CLI
diff --git a/.claude/skills/sync-security-issue/SKILL.md b/.claude/skills/sync-security-issue/SKILL.md
index b2e1cfb..3c3b9d0 100644
--- a/.claude/skills/sync-security-issue/SKILL.md
+++ b/.claude/skills/sync-security-issue/SKILL.md
@@ -1709,7 +1709,7 @@ In every other case — including already-published CVEs — regenerate.
 The minimum command, from the `<tracker>` clone root:
 
 ```bash
-uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
 ```
 
 That alone is enough. The script reads every template field from the
@@ -1757,7 +1757,7 @@ reason; the same scoping rule applies if you ever need to resolve
 the author by hand.
 
 ```bash
-uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> --attach
 ```
 
 If the *"Remediation developer"* field is empty at regeneration time
diff --git a/AGENTS.md b/AGENTS.md
index d4d9259..22c9b1c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -286,6 +286,7 @@ the active configuration before executing any command:
 | Placeholder | Resolves to | Source |
 |---|---|---|
 | `<project-config>` | The adopting project's `.apache-steward/` directory in its tracker repo. | Filesystem convention. |
+| `<framework>` | The framework's root — i.e. this repository. In adopting projects, `<project-config>/apache-steward/` (the submodule path); in framework standalone, `.` (the repository root). Used in `uv run` and other invocations that need to address the framework's `tools/<name>/` subtrees from a path the agent can resolve at the agent's current `cwd`. | Filesystem convention. |
 | `<tracker>` | The GitHub slug of the tracker repo (example: `airflow-s/airflow-s` for the Apache Airflow security team). | `<project-config>/project.md` → `tracker_repo` |
 | `<upstream>` | The GitHub slug of the upstream codebase the fixes land in (example: `apache/airflow`). | `<project-config>/project.md` → `upstream_repo` |
 | `<security-list>` | The project's security mailing list (example: `security@airflow.apache.org`). | `<project-config>/project.md` → `mailing_lists.security` |
diff --git a/tools/vulnogram/generate-cve-json/README.md b/tools/vulnogram/generate-cve-json/README.md
index 7376d66..cd030d0 100644
--- a/tools/vulnogram/generate-cve-json/README.md
+++ b/tools/vulnogram/generate-cve-json/README.md
@@ -38,20 +38,34 @@ workflow for the project itself.
 
 ## Run
 
-From the repository root:
+From the framework's root (this repository when running standalone;
+the `.apache-steward/apache-steward/` submodule path inside an
+adopting tracker repo):
 
 ```bash
 uv run --project tools/vulnogram/generate-cve-json generate-cve-json <ISSUE-NUMBER> [options]
 ```
 
+Skill files reference the same invocation via the `<framework>`
+placeholder so the path resolves in either context:
+
+```bash
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <ISSUE-NUMBER>
+```
+
+`<framework>` substitutes to `.apache-steward/apache-steward` in
+adopting projects and to `.` (the repository root) in framework
+standalone — see the placeholder convention in
+[`AGENTS.md`](../../../AGENTS.md#placeholder-convention-used-in-skill-files).
+
 Equivalent forms:
 
 ```bash
 # as a module
-uv run --project tools/vulnogram/generate-cve-json python -m generate_cve_json <ISSUE-NUMBER>
+uv run --project <framework>/tools/vulnogram/generate-cve-json python -m generate_cve_json <ISSUE-NUMBER>
 
 # from inside the project dir
-cd tools/vulnogram/generate-cve-json
+cd <framework>/tools/vulnogram/generate-cve-json
 uv run generate-cve-json <ISSUE-NUMBER>
 ```
 
diff --git a/tools/vulnogram/generate-cve-json/SKILL.md b/tools/vulnogram/generate-cve-json/SKILL.md
index c2765dd..cbc8275 100644
--- a/tools/vulnogram/generate-cve-json/SKILL.md
+++ b/tools/vulnogram/generate-cve-json/SKILL.md
@@ -259,7 +259,7 @@ prepares the (cached) virtualenv on first use and reuses it on later
 runs:
 
 ```bash
-uv run --project tools/vulnogram/generate-cve-json generate-cve-json <N> \
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json <N> \
   --output /tmp/<CVE-ID>.json \
   --version-start <earliest-affected-version>
 ```
@@ -273,7 +273,7 @@ needed in the normal flow. For a fix that landed in `3.2.2` and was
 first introduced in `3.0.0`, for example:
 
 ```bash
-uv run --project tools/vulnogram/generate-cve-json generate-cve-json 232 \
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json 232 \
   --output /tmp/CVE-2026-40913.json \
   --version-start 3.0.0
 ```
@@ -375,7 +375,7 @@ If the user also wants the JSON *attached* to the tracking issue itself
 add `--attach` to the invocation:
 
 ```bash
-uv run --project tools/vulnogram/generate-cve-json generate-cve-json 232 \
+uv run --project <framework>/tools/vulnogram/generate-cve-json generate-cve-json 232 \
   --output /tmp/CVE-2026-40913.json \
   --version-start 3.0.0 \
   --attach