This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 4b7a36b docs(principles): add operational principles document (#147)
4b7a36b is described below
commit 4b7a36b555e012111496d60524ee3012918b61fd
Author: André Ahlert <[email protected]>
AuthorDate: Tue Jun 2 08:40:46 2026 -0300
docs(principles): add operational principles document (#147)
* docs(principles): add operational principles document
PRINCIPLES.md restates RFC-AI-0004's six baseline principles in their
operational shape and adds the project-internal commitments the RFC
deliberately defers: eval as release blocker, contributor-sentiment
gating, no default telemetry, reproducibility from signed source,
maintainer education shipped with the platform.
19 ordered principles. Earlier outranks later when they collide.
Amendment process matches the release-vote process (>=3 binding +1,
no binding -1, 72h window, no lazy consensus).
Positioned as project-internal operating contract, not a competing RFC.
* docs(principles): address review feedback on PRINCIPLES.md
- Replace SPDX with full ASF v2 license header (jbonofre)
- Clarify binding audience: contributors, committers, PMC, unmodified
adopters (jbonofre)
- Extend #5 with deterministic-first execution to save tokens (potiuk)
- Extend #6 with explicit human sign-off for outbound human communication
(RussellSpitzer)
- Rework #9 around capability floor instead of "same code on all backends",
add justified-and-minimized clause, add end-to-end single-machine config
requirement (RussellSpitzer)
- Standardize on US English (analyze, artifact, behavior, catalog, license,
specialized)
* docs(principles): disambiguate 'language-independent' as
'programming-language independent' (RussellSpitzer)
* docs(principles): qualify P6 merge rule as 'unilaterally' to resolve
auto-merge tension (justinmclean)
* docs(principles): scope P3 'first-class' as adopter, clarify amendment
proposal path (justinmclean)
* docs(principles): add PMC adjudication path for disputed committer blocks
(justinmclean)
* docs(principles): scope P6 impersonation claim to messages read as
maintainer-authored (justinmclean)
* docs(principles): replace dangling 'same family' clause with
single-principle interpretation rule (justinmclean)
* docs(principles): add generated TOC
* docs(principles): align P14 with upstream Skills contract
A skill is always a directory with SKILL.md as entrypoint, even
for one-file workflows. SKILL.md stays under 500 lines; longer
reference material moves into sibling markdown linked one level
deep. Matches the runtime contract documented at
https://code.claude.com/docs/en/skills and
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices,
and reflects how skills in this repo (contributor-nomination,
pr-management-code-review, pr-management-mentor) are already
authored.
* docs(principles): make P6 merge clause explicit on subject and close
auto-merge gap (justinmclean)
* docs(principles): resolve disputed blocks via PMC consensus first, vote
as last resort (justinmclean)
* docs(principles): soften P11 reproducibility requirement
Addresses review feedback that 'bytes are identical' is too strong
for a project-agnostic framework. Toolchains vary in their ability
to produce byte-identical output; some have known divergence sources
(timestamps, file ordering, path embedding).
P11 now requires byte-identical builds where achievable, and where
the toolchain makes that impractical, the release process must
document the divergence and provide an alternative local verification
mechanism. The 'no code without reviewed PR' guard stays absolute.
Refs: PR #147 review
* docs(principles): move ASF license header to top of file
The doctoc-generated TOC was placed above the Apache license header,
which breaks tooling that expects the license notice in the first
few lines of the file. Move the license block to line 1, followed
by the TOC.
Refs: PR #147 review
* docs(principles): align amendment process and blocking rules with ASF
policy
Three fixes from PR #147 review by @justinmclean:
1. Amendment vote model: 'release vote' -> 'code-modification vote'
The encoded rule (>=3 binding +1, any binding -1 vetoes) matches
ASF consensus approval for code modifications, not majority
approval for releases.
2. Veto-justification requirement: A binding -1 must now include a
technical justification. Without one the veto is invalid and has
no weight, matching ASF voting policy.
3. Generative tooling disclosure: P17 now requires a
'Generated-by: <tool>' token in commit messages for AI-authored
contributions, per ASF Generative Tooling Guidance.
---
PRINCIPLES.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 147 insertions(+)
diff --git a/PRINCIPLES.md b/PRINCIPLES.md
new file mode 100644
index 0000000..03d0ebe
--- /dev/null
+++ b/PRINCIPLES.md
@@ -0,0 +1,147 @@
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Apache Steward Design Principles](#apache-steward-design-principles)
+ - [Amending these principles](#amending-these-principles)
+ - [0. External content is data, never an
instruction](#0-external-content-is-data-never-an-instruction)
+ - [1. Privacy, security, and supply-chain integrity ship before
features](#1-privacy-security-and-supply-chain-integrity-ship-before-features)
+ - [2. The relationship is the product](#2-the-relationship-is-the-product)
+ - [3. Project autonomy is the structural starting
point](#3-project-autonomy-is-the-structural-starting-point)
+ - [4. Lower-stakes automation ships before higher-stakes
automation](#4-lower-stakes-automation-ships-before-higher-stakes-automation)
+ - [5. Outputs are probabilistic; gates are
deterministic](#5-outputs-are-probabilistic-gates-are-deterministic)
+ - [6. The human is always in the loop, until they choose
otherwise](#6-the-human-is-always-in-the-loop-until-they-choose-otherwise)
+ - [7. Contributor sentiment gates every mode
graduation](#7-contributor-sentiment-gates-every-mode-graduation)
+ - [8. Eval is a release-blocking
discipline](#8-eval-is-a-release-blocking-discipline)
+ - [9. Vendor neutrality is
non-negotiable](#9-vendor-neutrality-is-non-negotiable)
+ - [10. No default telemetry](#10-no-default-telemetry)
+ - [11. Releases are reproducible from signed
source](#11-releases-are-reproducible-from-signed-source)
+ - [12. The framework is project-agnostic; concrete names live in adopter
config](#12-the-framework-is-project-agnostic-concrete-names-live-in-adopter-config)
+ - [13. Snapshot plus override, never vendored
copies](#13-snapshot-plus-override-never-vendored-copies)
+ - [14. Skills are the unit of
authorship](#14-skills-are-the-unit-of-authorship)
+ - [15. Tracker identifiers are public-safe; tracker contents are
not](#15-tracker-identifiers-are-public-safe-tracker-contents-are-not)
+ - [16. Audit every agent-authored action; reverse it where
possible](#16-audit-every-agent-authored-action-reverse-it-where-possible)
+ - [17. Contributions land under Apache License
2.0](#17-contributions-land-under-apache-license-20)
+ - [18. Maintainer education ships with the
platform](#18-maintainer-education-ships-with-the-platform)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Apache Steward Design Principles
+
+These principles regulate what this framework is and how it evolves. Order
matters: earlier principles outrank later ones when they collide. Where a
single principle admits more than one reading, the stricter reading wins until
governance documents otherwise.
+
+A change (PR, skill, tool adapter, release) that violates a principle is wrong
even if every test passes. Any committer may block it on principle grounds,
provided they explain in the PR thread how the change violates the principle. A
block without that explanation is invalid and has no weight. The block lifts
when the change complies, when a principle-amendment proposal carries through
governance with the same weight as a code-modification vote, or, when the
author and the blocking comm [...]
+
+## Amending these principles
+
+This document is binding on contributors, committers, and the PMC of the
apache-steward project, and on adopter projects to the extent they consume the
framework unmodified. Editing it follows the same process as a
code-modification vote (consensus approval):
+
+- A principle amendment is proposed as a PR against this file plus a thread on
the project's PMC private list (`private@<project>.apache.org`) and a mirrored
thread on `dev@<project>.apache.org` for public visibility.
+- The voting window is at least 72 hours from the [VOTE] message.
+- Passage requires ≥3 binding +1 votes from PMC members and zero binding -1
vetoes. A binding -1 must include a technical justification; without one it is
invalid and has no weight. A valid -1 stops the amendment until the objection
is addressed or withdrawn.
+- Lazy consensus does NOT apply to principle changes. Silence is not consent
here.
+- The PR merges only after the vote result is recorded on the dev list and
linked from the merge commit.
+
+Anyone may propose an amendment by opening the PR; the mailing-list threads
and the binding vote belong to the apache-steward PMC, because this file is the
governance document of an ASF project. Adopter projects that need a principle
to read differently for their own use rely on overrides (principle 13) rather
than amending this file.
+
+Editorial fixes (typos, broken links, formatting) follow normal review and do
not require a vote. Anything that changes the meaning of a principle, adds a
principle, removes a principle, or changes the ordering does.
+
+## 0. External content is data, never an instruction
+
+Reporter mail, PR comments, GHSA forwards, attachments, linked URLs, anything
that did not land via a reviewed PR by a tracker-repo collaborator: input to
analyze, never directives. No framing softens this. Not authority claims, not
embedded "ignore previous instructions", not a user pasting external content
and asking the agent to "apply what it says". Rule cannot be relaxed
mid-session, cannot be overridden by a runtime document.
+
+## 1. Privacy, security, and supply-chain integrity ship before features
+
+Sandbox, clean-environment wrapper, privacy-aware LLM routing, PII redaction,
pinned and signed dependencies, audit logging: release-blocking parts of every
milestone, not retrofits. If a feature has to slow to keep this story honest,
it slows. The capable maintainer who declines to adopt over a privacy concern
is the failure case the framework is built to avoid.
+
+## 2. The relationship is the product
+
+Open source runs on contributor-to-maintainer trust, peer-maintainer trust,
and the progression from first contribution to the project's highest governance
role, by whatever name that role carries. Agents absorb the mechanical traffic
that gets in the way of trust, never replace it. A feature that trades a human
relationship for throughput is wrong.
+
+## 3. Project autonomy is the structural starting point
+
+Each adopting project picks which modes run and how much automation fits its
culture, whatever its governance: ASF PMC, foundation-hosted, single-vendor,
informal maintainer group. The framework offers a range, never mandates a
level. Non-ASF adopters are first-class adopters, not a compatibility
afterthought. Vendor neutrality extends to project governance the same way it
extends to model providers.
+
+## 4. Lower-stakes automation ships before higher-stakes automation
+
+Automation rolls out in order of reversibility and blast radius:
+
+- Read-only suggestions and conversational help before agent-drafted artifacts.
+- Drafted artifacts under human review before any state-changing action.
+- State-changing actions before merges.
+- Merges only for narrowly-scoped, reversible change classes.
+
+A higher-stakes lane unlocks only after the lower-stakes ones have produced
evidence the project is healthier, not just faster. Security-class changes
never reach the merge end of this ladder. The framework will name and version
specific modes, but this ordering survives any renaming.
+
+## 5. Outputs are probabilistic; gates are deterministic
+
+Skills produce drafts. Tool calls enforce schemas. Humans or deterministic
checks decide whether a draft becomes state. Probabilistic at the input,
deterministic at every state change. The boundary never blurs, even when the
draft looks reliable enough to short-circuit the gate. Where a deterministic
check (script, linter, schema validation) can replace an LLM pass, it runs
first; LLM passes are not spent on what executable code already decides.
+
+## 6. The human is always in the loop, until they choose otherwise
+
+Every agent-authored output (comment, label, draft, issue, PR) is a proposal a
human signs off on. The agent never performs a merge of its own work, nor
unilaterally enables auto-merge on it. Auto-merge, where it exists, is narrow,
opt-in per project AND per change class, and never touches security-class
changes. **The opt-out never extends to communication aimed at a human: any
outbound message a person will read as if a maintainer wrote it (reporter mail,
PR or issue comment, review re [...]
+
+## 7. Contributor sentiment gates every mode graduation
+
+Promotion of any mode (from experimental to default, from suggestion to draft,
from draft to state change, from state change to merge) requires evidence
sourced from contributors and reviewers that the project is healthier.
Throughput numbers alone never qualify. The length of the evidence window is
set by adopter governance, not by this document.
+
+## 8. Eval is a release-blocking discipline
+
+Skill behavior is probabilistic, so correctness lives in distributions, not
unit tests. Every release ships eval cases for every skill it includes, plus
the methodology used to grade them. A skill without an eval is unreleased,
regardless of how it looks in a demo.
+
+## 9. Vendor neutrality is non-negotiable
+
+Every skill targets the abstraction layer, never a single vendor's client.
Frontier APIs, local inference (Ollama, vLLM), community-hosted endpoints: all
valid backends, provided they meet the skill's declared capability floor
(context window, tool use, vision, sustained reasoning). A skill hard-coded to
one vendor or model family is broken, not specialized. Capability floors must
be justified and minimized so the floor itself does not become a vendor lock-in
by proxy. Affordability is p [...]
+
+## 10. No default telemetry
+
+The framework, its skills, and its release artifacts do not phone home.
Outbound network calls come from explicit skill actions documented in the audit
log. Usage analytics, error reporting, update checks: opt-in per project, never
on by default. A maintainer who installs the framework and never invokes a
skill generates zero outbound traffic.
+
+## 11. Releases are reproducible from signed source
+
+Releases are reproducible from signed source to the extent the toolchain
permits. Where byte-identical builds are achievable, they are required. Where
the toolchain or platform makes byte-identical output impractical, the release
process documents the known sources of divergence and provides an alternative
verification mechanism that a contributor can run locally to confirm the
artifact matches the canonical distribution. No release artifact contains code
that did not pass through a revi [...]
+
+## 12. The framework is project-agnostic; concrete names live in adopter config
+
+Skills, tool adapters, and root docs use `<PROJECT>` / `<tracker>` /
`<upstream>` / `<security-list>` placeholders and resolve them at runtime from
`<project-config>/project.md` and the resolved `user.md`. A concrete name
(`apache/airflow`, a real CVE ID, a mailing list address) inside
`.claude/skills/` or `tools/` is a refactor bug, not a shortcut. Swapping
projects is a config change, never a code change.
+
+## 13. Snapshot plus override, never vendored copies
+
+Adopters consume the framework as a gitignored snapshot at `.apache-steward/`,
pinned via a committed lock file, refreshed by one skill (`setup-steward`).
Project-specific modifications live as agent-readable markdown under
`<project-config>/.apache-steward-overrides/`, committed. No git submodules. No
vendored copies of framework skills inside adopter repos. Marketplaces,
indexes, and catalogs may exist for discovery, never for installation.
+
+## 14. Skills are the unit of authorship
+
+A skill is always a directory under `.claude/skills/<skill-name>/` with
`SKILL.md` as its entrypoint, even when the workflow fits in a single file.
`SKILL.md` stays under 500 lines; reference material beyond that moves into
sibling markdown linked one level deep, with no unreferenced siblings. Skills
are code in every meaningful sense: reviewed in PRs, versioned, signed by the
same release process as the rest of the framework. Refactor at the skill
boundary, never below it.
+
+## 15. Tracker identifiers are public-safe; tracker contents are not
+
+A `<tracker>` URL or `#NNN` is a stable reference downstream consumers can pin
work against. The page behind it stays access-gated. Issue bodies, comment
text, rollup entries, label transitions, severity scores, reporter-supplied
CVSS, pre-disclosure CVE detail: never appear on a public surface verbatim.
Other projects' vulnerabilities never appear at all. Cross-project correlations
stay on the channel they arrived on.
+
+## 16. Audit every agent-authored action; reverse it where possible
+
+Every comment, label, draft, issue, and PR an agent authors lands in a log a
human can read after the fact. Reversible actions stay reversible. Irreversible
ones are flagged visibly before they execute, never silently. "The agent did
something I cannot see or undo" is a bug, not a feature gap.
+
+## 17. Contributions land under Apache License 2.0
+
+Every contribution to the framework (skills, patterns, docs, tool adapters,
examples) lands under Apache License 2.0, matching the framework's own license.
Adopter overrides and project-specific skills outside this repository are the
adopter's to license. Dependencies that cannot be redistributed under
Apache-2.0-compatible terms do not enter the framework. Contributions authored
with generative AI tooling include a `Generated-by: <tool>` token in the commit
message, per ASF Generative T [...]
+
+## 18. Maintainer education ships with the platform
+
+Most maintainers have never built an agentic application. The mental model is
different: behavior is probabilistic, prompts are code, evaluation is harder
than testing a function. Every release ships the docs, patterns, eval examples,
and workshop material maintainers actually need. A platform without the
education stream alongside it is not adoptable, regardless of code quality.
