Skip to content

fix(docs): point <security-list> at the config key that exists - #1058

Open
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:fix/security-list-placeholder
Open

fix(docs): point <security-list> at the config key that exists#1058
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:fix/security-list-placeholder

Conversation

@potiuk

@potiuk potiuk commented Aug 1, 2026

Copy link
Copy Markdown
Member

Summary

  • Both places that tell an agent how to resolve <security-list> named mailing_lists.security — a key that does not exist anywhere in the tree. The adopter manifest declares security_list, under a ## Mailing lists heading.
  • An agent following either instruction looks for a key it will never find, and cannot resolve the placeholder.
  • Fixed in AGENTS.md § Placeholder convention and in skills/security-cve-allocate/SKILL.md, where the sibling entries already use the flat form and this one was the odd one out.

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)

Test plan

  • prek run passes on both changed files
  • Verified against projects/_template/project.md that security_list is the declared key, alongside private_list, users_list, dev_list, announce_list, commits_list
  • Checked the rest of the placeholder table rather than assuming: tracker_repo, upstream_repo, and upstream_default_branch all resolve in the template. mailing_lists.security was the only cited key with no definition, so this is an isolated error and not a pattern
  • Confirmed mailing_lists appears nowhere in the repo except the two lines this PR corrects

RFC-AI-0004 compliance

  • HITL — any new mutation is gated on explicit user confirmation
  • Sandbox — no new unrestricted host access; network reach declared in the adapter
  • Vendor neutrality — the placeholder mechanism is what keeps concrete project values out of skills; a placeholder that cannot be resolved is that mechanism failing quietly
  • Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
  • Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
  • Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Follow-up to #1055. The related org-level naming problem is #1057.

Notes for reviewers (optional)

What I deliberately did not change, because it looks like the obvious tidy-up and is wrong:

skills/security-issue-sync/github-advisory.md uses <security-team-list> once, and it is tempting to normalise that to the registered <security-list>. It should not be. The two appear in the same instruction and mean different addresses:

Create a draft email to the org's advisory-admin security team (<security-team-list>) … Always CC the project <security-list> so the project security team stays looped in.

Collapsing them would turn that into "email X and CC X", quietly dropping the project security team from an advisory relay. I started to make that change and stopped after reading the surrounding sentence.

The underlying problem is that the org-level address has three names in the tree — <security-team-list>, <asf-security-list> (ASF-branded, in a governance-agnostic framework), and the config path security_inbox.foundation_security_address — and none is registered in the placeholder table. That wants deciding deliberately rather than guessing at inside a typo fix, so it is #1057.

Both places telling an agent how to resolve `<security-list>` named
`mailing_lists.security`, which is not a key anywhere in the tree. The
adopter manifest declares `security_list` under a `## Mailing lists`
heading, so an agent following either instruction would look for a key
that does not exist and be unable to resolve the placeholder.

- `AGENTS.md` § Placeholder convention — the source column for
  `<security-list>`.
- `skills/security-cve-allocate/SKILL.md` — the resolution block, where
  the sibling entries already use the flat form (`tracker_repo:`,
  `upstream_repo:`) and this one was the odd one out. Its arrow was also
  misaligned by a space against the entries around it; fixed while there.

Verified against `projects/_template/project.md`: `security_list`,
`private_list`, `users_list`, `dev_list`, `announce_list`,
`commits_list` are the declared keys. Every other placeholder the table
cites — `tracker_repo`, `upstream_repo`, `upstream_default_branch` —
does resolve, so this was an isolated error rather than a pattern.

Not touched, deliberately: `skills/security-issue-sync/github-advisory.md`
uses `<security-team-list>` for the *org-level* advisory-admin address and
`<security-list>` for the project list, in the same sentence. They are
different addresses, so collapsing them would turn "email X, CC the
project list" into "email X, CC X". The org-level address has no single
agreed name — `<security-team-list>` here, `<asf-security-list>` in
AGENTS.md, and `security_inbox.foundation_security_address` as the actual
org-level config path — which wants deciding on its own, not guessing at
inside a typo fix. Filed separately.

Generated-by: Claude Code (Opus 5)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant