Skip to content

docs(agents): document <PROJECT> vs <project>, and catch spaced variants - #1154

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:fix/placeholder-convention-gaps
Sep 7, 2026
Merged

docs(agents): document <PROJECT> vs <project>, and catch spaced variants#1154
potiuk merged 1 commit into
apache:mainfrom
potiuk:fix/placeholder-convention-gaps

Conversation

@potiuk

@potiuk potiuk commented Sep 7, 2026

Copy link
Copy Markdown
Member

Summary

  • <PROJECT> (display name, 84 uses) and <project> (infrastructure slug, 313 uses) are both load-bearing — across skills, tool docs, organizations/ASF/organization.md and PRINCIPLES.md — yet neither had a row in the placeholder table in AGENTS.md, which closes with "do not invent new placeholders". Answering "is <project> an invented placeholder?" needed a repo-wide grep instead of a table lookup. Both now have a row, plus a note stating the difference explicitly: two placeholders holding two different values, not one value in two casings. Substituting one where the other belongs produces something wrong rather than mis-cased — Apache Foo.apache.org is not a hostname.
  • The same case-only difference is a linter hazard. FORBIDDEN_PATTERNS is matched with grep -F, so the name:"airflow" entry added in fix(skills): derive the two remaining Airflow literals from project config #1144 only caught the no-space spelling — GraphQL, YAML and JSON all accept name: "airflow" equally, and that form passed every pattern in the list. Patterns whose surrounding syntax admits optional whitespace now live in a new FORBIDDEN_REGEXES array matched with grep -E; the two arrays share one match-reporting path. Fixed strings stay the default — easier to read, and they cannot misfire on regex metacharacters.

Both gaps surfaced while reviewing #1144; this is the follow-up that PR's review nit pointed at.

Type of change

  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • CI / dev loop (prek, workflows, validators)

Test plan

  • prek run passes on both changed files — including lychee (the new link to tools/dev/check-placeholders.sh resolves) and doctoc (no headings changed, so the TOC is untouched).
  • Linter is clean on the current tree: tools/dev/check-placeholders.sh exits 0.
  • Regression, new behaviour: planting repository(owner: "apache", name: "airflow") in skills/ is now caught — it was not caught before this change.
  • Regression, existing behaviour: planting repository(owner:"apache",name:"airflow") is still caught, so the grep -Fgrep -E move loses no coverage.
  • bash -n tools/dev/check-placeholders.sh clean.
  • No eval suites affected — no SKILL.md or step prompt material changes, so per AGENTS.md § When the rule fires this is the prose/tooling row that needs no fixture rerun.

RFC-AI-0004 compliance

  • Vendor neutrality — this PR strengthens the mechanical gate that enforces placeholder discipline, and documents the two placeholders it protects.

Linked issues

Follow-up to #1144.

Two gaps that surfaced while reviewing apache#1144.

`<PROJECT>` (display name, 84 uses) and `<project>` (infrastructure
slug, 313 uses) are both load-bearing across skills, tool docs, the ASF
organization manifest, and PRINCIPLES.md — but neither appeared in the
placeholder table in AGENTS.md, which closes with "do not invent new
placeholders". Answering "is `<project>` an invented placeholder?"
required a repo-wide grep rather than a table lookup. Both now have a
row, plus a note stating the difference explicitly: they hold two
different values, not one value in two casings. Substituting one where
the other belongs yields something wrong rather than mis-cased —
`Apache Foo.apache.org` is not a hostname.

The same case-only difference is a linter hazard. `FORBIDDEN_PATTERNS`
is matched with `grep -F`, so the `name:"airflow"` entry added in apache#1144
only caught the no-space spelling; GraphQL, YAML and JSON all accept
`name: "airflow"` equally, and that form passed every pattern in the
list. Rather than add a second fixed string per spacing, patterns whose
surrounding syntax admits optional whitespace move to a new
`FORBIDDEN_REGEXES` array matched with `grep -E`; the two arrays share
one match-reporting path. Fixed strings stay the default — they are
easier to read and cannot misfire on regex metacharacters.

Verified: `check-placeholders.sh` is clean on the current tree, and
flags both `name:"airflow"` and `name: "airflow"` when either is
planted in `skills/`. `prek run` passes on both changed files,
including `lychee` and `doctoc`.

Generated-by: Claude Code (Opus 5)
@potiuk
potiuk merged commit e9679f9 into apache:main Sep 7, 2026
9 checks passed
potiuk added a commit that referenced this pull request Sep 8, 2026
The marker sat at a1cff44, 17 commits behind main. Bumping it alone
would claim those commits are described by the specs, so the drift is
closed first.

Specs updated for what actually shipped:

- meta-and-quality-tooling: skill-evals errors, rather than passing, when
  a case's CLI produced no gradeable output (#1161).
- security-reporting: the tracker dashboard projects the current partial
  bucket to its end-of-bucket value, splitting RATE series (accumulate
  from zero) from LEVEL series (carry over), and deliberately not
  projecting mean-based signals (#1158).
- project-agnosticism: <PROJECT> and <project> are two placeholders
  holding different values, and the lint carries both spellings plus
  spaced variants (#1154).
- adapters: the forwarder relay's contact_handle defaults to an
  org-level shared inbox rather than a named individual (#1135). The
  multi-hop coordinator case is designed in RFC-AI-0008 and unimplemented.
- issue-management-family: the family's eval suites, and the note that
  --cli runs belong outside a credential-denying sandbox (#1145).

Commits needing no spec change: #1152, #1143 and #1156 updated their own
specs in-commit; #1149, #1147, #1151 are behaviour-preserving bug fixes;
#1155 and #1141 are CI and dependency chores; #1159's spec edits landed
with it; #1144 removes hardcoded literals that no spec asserted.

One genuine gap recorded rather than papered over: no spec covers
marketplace distribution or the dev-version stamping rule from #1160,
which is load-bearing because `claude plugin update` compares version
strings, not commit SHAs. Logged in adoption-and-setup as wanting its own
spec.

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