This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new d42cbef47 chore: fold Fory review skill into agent guidance (#3779)
d42cbef47 is described below
commit d42cbef4771b58fe54b3cd947eab8642f09ba60a
Author: Shawn Yang <[email protected]>
AuthorDate: Tue Jun 23 14:16:32 2026 +0530
chore: fold Fory review skill into agent guidance (#3779)
## Why?
## What does this PR do?
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence of the final clean AI review results
from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes.
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
.agents/README.md | 12 ++-
.agents/ci-and-pr.md | 87 ++++++++++++++++++++-
.agents/skills/fory-code-review/SKILL.md | 90 ----------------------
.agents/skills/fory-code-review/agents/openai.yaml | 21 -----
.../references/lesson-derived-red-flags.md | 45 -----------
.../references/review-checklist.md | 53 -------------
.../references/validation-command-matrix.md | 79 -------------------
.github/pull_request_template.md | 4 +-
AGENTS.md | 11 ++-
AI_POLICY.md | 20 ++---
CONTRIBUTING.md | 3 +-
docs/DEVELOPMENT.md | 4 +
12 files changed, 123 insertions(+), 306 deletions(-)
diff --git a/.agents/README.md b/.agents/README.md
index ed0e89ae3..d850cd3c7 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -6,7 +6,8 @@ Load `AGENTS.md` first. Do not load every file under `.agents/`
by default; read
- `repo-reference.md`: repo layout, protocol overview, compiler notes, and
runtime map.
- `docs-and-formatting.md`: docs, specs, markdown formatting, publishing
notes, and generated-artifact rules.
-- `ci-and-pr.md`: GitHub Actions triage, PR expectations, and commit message
format.
+- `ci-and-pr.md`: code review workflow, review red flags, validation guidance,
GitHub Actions
+ triage, PR expectations, and commit message format.
- `testing/integration-tests.md`: `integration_tests/` prerequisites,
regeneration rules, and commands.
## Runtime References
@@ -44,12 +45,17 @@ Load `AGENTS.md` first. Do not load every file under
`.agents/` by default; read
- relevant runtime file under `languages/`
- `docs-and-formatting.md`
- skill-specific references if using a performance skill
-- PR review or CI triage:
+- Apache Fory PR, branch, commit-range, local-diff code review, or CI triage:
- `AGENTS.md`
- `ci-and-pr.md`
- relevant runtime file under `languages/`
+- Independent general reviewer required by `AI_POLICY.md`:
+ - Follow the `AGENTS.md` independent-review carve-out if tooling auto-loads
`AGENTS.md`.
+ - Do not load `ci-and-pr.md` or use copied Fory-specific review checklist
prompts.
## Canonicality
- Treat the files in this directory as the canonical agent-specific guidance.
-- Existing skill reference matrices under `.agents/skills/` are task-focused
quick references; when they overlap with runtime rules, prefer the matching
file in `languages/` or `testing/`.
+- Review workflow, review red flags, and PR preparation rules belong in
`ci-and-pr.md`;
+ runtime-specific details belong in `languages/`, and cross-language
validation details belong in
+ `testing/`.
diff --git a/.agents/ci-and-pr.md b/.agents/ci-and-pr.md
index 9a3ccd0fe..6f7171f09 100644
--- a/.agents/ci-and-pr.md
+++ b/.agents/ci-and-pr.md
@@ -1,6 +1,8 @@
# CI And PR Guidance
-Load this file when triaging GitHub Actions, preparing a pull request, or
writing commit messages.
+Load this file when doing Apache Fory code reviews of PRs, branches, commit
ranges, or local diffs;
+triaging GitHub Actions; preparing a pull request; or writing commit messages.
Do not load this file
+when explicitly acting as the independent general reviewer required by
`AI_POLICY.md`.
## Workflow Pointers
@@ -37,6 +39,89 @@ Typical flow:
- Before pushing PR work, verify `git remote -v`, the current branch, and the
PR head repository/branch; do not infer push targets from contributor names.
- Do not stage or commit task scratch files such as `tasks/task-*.md`,
`tasks/lessons.md`, or synthesis/plan notes unless the user explicitly asks to
version them.
+## Review Subagents
+
+- When the task environment supports review subagents, perform Apache Fory
code review in a fresh read-only review subagent. The main agent coordinates
scope, sanity-checks findings, and reports the final review.
+- Reuse the same review subagent for later review passes on the same feature
unless the user or workflow requires a fresh reviewer. Start a fresh review
subagent for a different feature, PR, issue, branch, commit range, local diff
topic, or subsystem review.
+- Keep review subagents read-only. They must not edit files, apply patches,
run tests, run builds, run benchmarks, run linters, install packages, commit,
push, fix tests, update docs, or perform implementation work.
+- Review subagents report findings or an explicit no-findings result to the
caller. The main agent decides whether any separate implementation, CI fixing,
or verification task should happen.
+
+## Review Workflow
+
+1. Define the review target.
+
+- Determine whether the target is a GitHub PR, branch, commit range, local
diff, or file subset.
+- For GitHub PR review, create and use a dedicated local worktree before
checking out or fetching the PR branch unless the user explicitly asks to reuse
the current workspace.
+- If reviewing against main, run `git fetch apache main` before diffing.
+- Inspect `git diff --stat` first, then inspect the full patch by touched
subsystem.
+
+2. Load focused context.
+
+- Protocol, type mapping, xlang, `TypeMeta`, `TypeInfo`, reference tracking,
schema evolution, or wire-format changes require the relevant
`docs/specification/**` sections.
+- Runtime-specific changes require the matching `.agents/languages/*.md` file.
+- Runtime cleanup or cross-language alignment changes require comparing the
changed ownership/API shape to the reference runtimes before judging drift,
usually C++ then Rust or Java.
+- Cross-language changes require `.agents/testing/integration-tests.md`.
+- Documentation, public API, benchmark report, or generated-artifact changes
require `.agents/docs-and-formatting.md`.
+
+3. Inspect in priority order.
+
+- Correctness, data corruption, security, and protocol drift.
+- Cross-language consistency and native/xlang behavior boundaries.
+- Performance regressions or invalid benchmark methodology.
+- Public API growth, legacy shims, wrapper layers, and architecture drift.
+- Missing tests, wrong test placement, and missing docs/spec updates.
+
+4. Validate each finding.
+
+- Tie every finding to exact changed lines.
+- Explain the concrete failure mode or regression risk.
+- State why the current code is wrong or incomplete, not only that it differs
from another style.
+- Recommend the missing test, benchmark, spec update, or doc update when that
is the gap.
+
+5. Report findings.
+
+- Findings come first and are ordered by severity.
+- Keep overview and change summary brief and secondary.
+- If there are no findings, say that explicitly and mention residual risks or
testing gaps.
+- If review comments will be posted on GitHub, write them as concise inline
comments with enough context for the author to act.
+
+## Review Red Flags
+
+- One runtime changes xlang or protocol behavior while other affected runtimes
are not updated or explicitly ruled out.
+- Compatible-mode, type-mapping, or wire-format semantics are described from
memory instead of current specs.
+- Runtime ownership moves into broad facades or helper layers instead of the
resolver, context, buffer, stream, or runtime type that owns the state.
+- Removed APIs come back as aliases, shims, or thin wrappers without a clear
user-owned reason.
+- Hot shared paths gain mode booleans, per-call allocations, callback objects,
holder objects, wrapper round trips, or unnecessary forwarding helpers.
+- Benchmark-only flags, payload identity caches, fixture-specific shortcuts,
or serializer-specific conversions inside timed loops change what is measured.
+- Benchmark comparisons are run concurrently on one host, based on smoke
settings, or reported without regenerated `docs/benchmarks/**` artifacts when
benchmark logic changed.
+- Two objects appear to own one reader or writer index.
+- Stream bind or rebind paths do not detach stale backlinks.
+- Flush behavior depends on implicit side effects instead of one explicit
owner.
+- Stream read-loop comments or fixes assume `(0, nil)` from a socket reader
must be fatal immediately.
+- Claimed cleanup is not backed by a full-tree search or exact command output.
+- Documentation overstates runtime support, benchmark conclusions, or
competitive claims beyond the evidence in code and tests.
+
+## Review Validation Matrix
+
+Canonical runtime-specific command rules live in `.agents/languages/*.md`, and
cross-language
+validation rules live in `.agents/testing/integration-tests.md`. This matrix
is a review-oriented
+shortcut for spotting missing evidence.
+
+Use the smallest command set that proves the changed behavior. If protocol or
xlang behavior changed, require the relevant cross-language tests even when the
author did not run them yet.
+For review-only tasks, use this matrix to identify missing verification
evidence and recommend
+commands; do not run these commands from a read-only review subagent. Run
commands only during an
+implementation, CI-fix, or verification task, or when the user explicitly asks
for command execution.
+
+- Repo-wide formatting/lint: `bash ci/format.sh --all`
+- Java: from `java/`, `mvn -T16 spotless:check`, `mvn -T16 checkstyle:check`,
`mvn -T16 test`, or targeted `mvn -T16 test -Dtest=<Class>#<method>`
+- C#: from `csharp/`, `dotnet format Fory.sln --verify-no-changes`, `dotnet
build Fory.sln -c Release --no-restore`, and `dotnet test Fory.sln -c Release`
+- C++: from `cpp/`, `bazel build //cpp/...` and `bazel test $(bazel query
//cpp/...)`; only add `--config=x86_64` on `x86_64` or `amd64`
+- Python: from `python/`, `ruff format .`, `ruff check .`,
`ENABLE_FORY_CYTHON_SERIALIZATION=0 pytest -v -s .`, and
`ENABLE_FORY_CYTHON_SERIALIZATION=1 pytest -v -s .`
+- Rust: from `rust/`, `cargo fmt --check`, `cargo clippy --all-targets
--all-features -- -D warnings`, and `cargo test --features tests`
+- Swift: from `swift/`, `swiftlint lint --config .swiftlint.yml`, `swift
build`, and `swift test`
+- Go: from `go/fory/`, `go fmt ./...` and `go test -v ./...`
+- Xlang matrix triggers: for xlang behavior, type mapping, protocol bytes,
compatible mode, `TypeMeta`, or cross-language container semantics, require
`org.apache.fory.xlang.CPPXlangTest`, `org.apache.fory.xlang.CSharpXlangTest`,
`org.apache.fory.xlang.RustXlangTest`, `org.apache.fory.xlang.GoXlangTest`, and
`org.apache.fory.xlang.PythonXlangTest`; include
`org.apache.fory.xlang.SwiftXlangTest` when Swift xlang behavior changes.
+
## Common CI Failures
- Code style failures: run the relevant formatter (`clang-format`, `prettier`,
`spotless:apply`, `dotnet format`, `cargo fmt`, and so on).
diff --git a/.agents/skills/fory-code-review/SKILL.md
b/.agents/skills/fory-code-review/SKILL.md
deleted file mode 100644
index 5085c57b9..000000000
--- a/.agents/skills/fory-code-review/SKILL.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-name: fory-code-review
-description: Review Apache Fory pull requests, branches, commits, or diffs
with a Fory-specific checklist. Use when auditing code in this repository for
protocol or xlang regressions, performance or benchmark-methodology issues,
cross-language inconsistencies, accidental public API growth, runtime ownership
drift, missing tests, or docs/spec mismatches. Also use before posting Fory
review findings inline to GitHub.
----
-
-# Fory Code Review
-
-## Mission
-
-Find the highest-value bugs, regressions, and missing verification in Apache
Fory changes. Prioritize correctness, protocol safety, performance discipline,
and maintainability over style-only comments.
-
-## Start Here
-
-1. Always perform the code review in a subagent. The main agent coordinates
scope, gathers the subagent's findings, sanity-checks them, and reports the
final review.
-2. Reuse the same review subagent for later review passes on the same feature
unless the user explicitly asks to review that feature in a new subagent.
-3. Do not reuse a review subagent across different features; start a new
subagent for each distinct feature or review topic.
-4. The review subagent must be read-only: it must not write code, apply
patches, create commits, push branches, fix tests, or update docs. It sends
review findings or an explicit no-findings result back to the caller.
-5. If the target is a GitHub PR, create a new local git worktree for the
review before checking out or fetching the PR branch.
-6. Do not switch the current branch or reuse the current worktree for PR
review unless the user explicitly asks for that.
-7. If reviewing against main, run `git fetch apache main` before diffing.
-8. Inspect the changed files first and cluster them by subsystem.
-9. Load only the references needed for the touched areas:
- - `references/review-checklist.md`
- - `references/lesson-derived-red-flags.md`
- - `references/validation-command-matrix.md`
- - matching runtime docs under `../../languages/*.md` when the patch is
language-specific
-
-## Subagent Reuse
-
-- Treat each feature under review as the reuse key. A feature may be a PR,
issue, branch, commit range, local diff topic, or clearly named subsystem
change.
-- When the user asks for another pass on the same feature, send the updated
context to the existing review subagent and ask it to continue from its prior
review state.
-- When the user asks to review a different feature, spawn a fresh review
subagent even if the same files, language, or subsystem are involved.
-- If the user explicitly requests a new subagent for the same feature, honor
that request and do not reuse the prior subagent.
-- Keep implementation work, CI fixing, and non-review exploration out of the
review subagent. The review subagent reports comments to the caller; the caller
decides whether any separate implementation task should happen.
-
-## Review Workflow
-
-1. Define the review target.
-
-- Determine whether the user wants a review of a PR, branch, commit range, or
local diff.
-- Assign the target to the correct review subagent using the Subagent Reuse
rules before inspecting code.
-- For a GitHub PR, create and use a dedicated local worktree for the review.
Keep the current worktree and branch unchanged unless the user explicitly
requests otherwise.
-- In that worktree, fetch the PR head and review there instead of checking out
the PR branch in the current workspace.
-- Prefer `git diff --stat` first, then inspect the full patch only for touched
subsystems.
-
-2. Load focused context.
-
-- Protocol, type mapping, xlang, `TypeMeta`, `TypeInfo`, ref tracking, or
schema evolution changes:
- - Read the relevant `docs/specification/**` sections before reviewing
behavior.
-- Benchmark or performance changes:
- - Review both benchmark code and generated `docs/benchmarks/**` artifacts.
-- Runtime cleanup or cross-language alignment changes:
- - Compare the changed ownership/API shape to the reference runtimes first,
usually C++ then Rust/Java.
-
-3. Inspect in this priority order.
-
-- Correctness, data corruption, security, and protocol drift.
-- Cross-language consistency and native/xlang behavior boundaries.
-- Performance regressions or invalid benchmark methodology.
-- Public API growth, legacy shims, wrapper layers, and architecture drift.
-- Missing tests, wrong test placement, and missing docs/spec updates.
-
-4. Validate each finding.
-
-- Tie the finding to exact changed lines.
-- Explain the concrete failure mode or regression risk.
-- State why the current code is wrong or incomplete, not only that it differs
from another style.
-- Recommend the missing test, benchmark, or spec/doc update when that is the
gap.
-
-5. Report findings.
-
-- Findings first, ordered by severity.
-- Keep overview and change summary brief and secondary.
-- If there are no findings, say that explicitly and mention residual risks or
testing gaps.
-
-## Hard Rules
-
-- Do not lead with style nits when there are correctness or verification risks.
-- Do not write code, edit files, apply patches, commit, push, or fix tests
from the review subagent.
-- Treat benchmark-shape tricks, payload-specific caches, and methodology
changes as real findings.
-- Treat undocumented public API additions, compatibility shims, and one-line
wrapper growth as findings when they increase maintenance surface without clear
need.
-- Treat protocol or performance claims without verification evidence as
incomplete.
-- When stream read loops are involved, remember that `(0, nil)` can be
transient; do not assume immediate failure is correct.
-- If the user wants comments posted on GitHub, produce findings suitable for
inline comments, then use `gh-pr-inline-review` to publish them.
-
-## Output Expectations
-
-- Use clickable file references with line numbers.
-- Keep each finding concrete: impact, evidence, and required fix.
-- Mention missing verification commands when the patch touches protocol,
performance, or cross-language behavior.
diff --git a/.agents/skills/fory-code-review/agents/openai.yaml
b/.agents/skills/fory-code-review/agents/openai.yaml
deleted file mode 100644
index 2b423c171..000000000
--- a/.agents/skills/fory-code-review/agents/openai.yaml
+++ /dev/null
@@ -1,21 +0,0 @@
-# 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.
-
-interface:
- display_name: "Fory Code Review"
- short_description: "Review Apache Fory changes for protocol, perf, and API
risks"
- default_prompt: "Review Apache Fory changes with a Fory-specific checklist
focused on protocol correctness, cross-language consistency, benchmark rigor,
API discipline, missing tests, and docs/spec gaps."
diff --git
a/.agents/skills/fory-code-review/references/lesson-derived-red-flags.md
b/.agents/skills/fory-code-review/references/lesson-derived-red-flags.md
deleted file mode 100644
index f27a0766f..000000000
--- a/.agents/skills/fory-code-review/references/lesson-derived-red-flags.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Lesson-Derived Red Flags
-
-## Protocol Drift
-
-- One runtime changed, but the same xlang behavior exists in other runtimes.
-- Helper names were unified, but signatures still hard-code mode-specific
types.
-- The patch adds explicit `if (xlang)` branching where the protocol is shared.
-- Compatible-mode or type-mapping semantics are described from memory instead
of current spec text.
-
-## Benchmark Methodology Problems
-
-- Benchmark-only config flags or shortcuts bypass real runtime work.
-- Serializer-specific model conversion happens inside timed loops without
being called out.
-- Before/after results were gathered from parallel benchmark runs on one host.
-- Reports or plots were not regenerated after benchmark logic changed.
-- Conclusions are drawn from smoke settings or noisy single-shot runs.
-
-## API And Architecture Drift
-
-- Removed APIs come back as aliases or shims.
-- Thin wrappers and pass-through helpers accumulate instead of being deleted.
-- Public API grows to fix an internal bug.
-- Language-local wrapper types, pending-state stacks, or side caches appear
without matching reference-runtime concepts.
-- Wrapper layers retain ownership that should live in resolver/context/buffer
types.
-
-## Streaming And Buffer Risks
-
-- Two objects appear to own one reader/writer index.
-- Stream bind or rebind paths do not detach stale backlinks.
-- Flush behavior depends on implicit side effects instead of one explicit
owner.
-- Review comments assume `(0, nil)` from a socket reader must be fatal
immediately.
-
-## Tests And Verification Gaps
-
-- Tests live in the wrong package or language suite for the behavior under
review.
-- Protocol or xlang changes lack the required cross-language test coverage.
-- Performance-sensitive changes have no benchmark or regression evidence.
-- Claimed cleanup is not backed by a full-tree search or exact command output.
-
-## Docs And Claim Precision
-
-- Language counts or support coverage are phrased as a fixed closed set.
-- Broad competitive claims are not split into concrete technical dimensions.
-- Titles or summaries overstate what the body proves.
-- Package-facing docs point to the wrong canonical destination.
diff --git a/.agents/skills/fory-code-review/references/review-checklist.md
b/.agents/skills/fory-code-review/references/review-checklist.md
deleted file mode 100644
index 47b840008..000000000
--- a/.agents/skills/fory-code-review/references/review-checklist.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Review Checklist
-
-## 1. Scope And Diff Setup
-
-- Identify the exact review target: `apache/main...HEAD`, PR branch, commit
range, or file subset.
-- Run `git diff --stat` before deep inspection.
-- If the review baseline is `apache/main`, refresh it first with `git fetch
apache main`.
-
-## 2. Protocol And Xlang
-
-- Did the patch touch `docs/specification/**`, `TypeMeta`, `TypeInfo`, type
IDs, ref flags, schema evolution, or xlang header/state?
-- Did the author update every affected runtime, or explicitly prove why the
other runtimes are already aligned?
-- Does the change preserve the intended boundary: xlang changed only where
required, native unchanged unless explicitly requested?
-- Are cross-language tests required but missing?
-- Does the implementation follow current spec text instead of a remembered
older behavior?
-
-## 3. Runtime Ownership And API Shape
-
-- Does the patch move ownership to the right layer (`TypeResolver`,
`ReadContext`, `WriteContext`, buffer/stream owner) instead of bloating `Fory`
facades?
-- Does it introduce wrappers, carrier objects, pending-state stacks, or side
caches that do not exist in the reference runtimes without clear evidence?
-- Does it reintroduce removed APIs, aliases, or compatibility shims against
explicit direction?
-- Are there new one-line forwarding helpers that should be inlined?
-- Are mode booleans or mode-specific parameter types leaking into hot shared
paths?
-
-## 4. Performance And Benchmarks
-
-- Does the patch optimize the runtime rather than the benchmark harness?
-- Does it depend on repeated payload identity, root-only shortcuts, or
fixture-specific behavior?
-- Were benchmark comparisons run sequentially, not concurrently?
-- If benchmark logic/reporting changed, were markdown reports and plots under
`docs/benchmarks/**` refreshed?
-- Are throughput and size comparisons apples-to-apples across languages and
serializer modes?
-
-## 5. Tests And Verification
-
-- Are tests in the right subsystem instead of whichever suite was convenient?
-- Are there targeted regressions tests for the changed behavior?
-- If protocol or xlang behavior changed, is the relevant xlang matrix called
out?
-- If performance-sensitive code changed, is there benchmark or regression
evidence?
-- Do the reported commands match the touched language/module?
-
-## 6. Docs And Public Claims
-
-- Are README, guides, specs, or benchmark docs required by the code change?
-- Do the docs use precise terminology and current semantics?
-- Are tables, captions, and summaries consistent with the body text?
-- Are canonical links and references present where the patch depends on prior
docs or published articles?
-
-## 7. Review Output
-
-- Findings first.
-- Order by severity.
-- Include file/line references.
-- If no findings, still state residual risk or testing gaps.
diff --git
a/.agents/skills/fory-code-review/references/validation-command-matrix.md
b/.agents/skills/fory-code-review/references/validation-command-matrix.md
deleted file mode 100644
index 372c847bc..000000000
--- a/.agents/skills/fory-code-review/references/validation-command-matrix.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Validation Command Matrix
-
-Use the smallest command set that proves the changed behavior. If protocol or
xlang behavior changed, call out the cross-language tests that should run even
if the author did not run them yet.
-
-Canonical runtime-specific rules now live under `../../../languages/*.md` and
`../../../testing/integration-tests.md`. Use this file as the review-oriented
shortcut matrix.
-
-## Repo-Wide Anchors
-
-- Format/lint sweep: `bash ci/format.sh --all`
-- Refresh remote main before main-branch comparison: `git fetch apache main`
-
-## Java
-
-- Build/test from `java/`
-- Typical checks:
- - `mvn -T16 spotless:check`
- - `mvn -T16 checkstyle:check`
- - `mvn -T16 test`
- - targeted: `mvn -T16 test -Dtest=<Class>#<method>`
-
-## C\#
-
-- Build/test from `csharp/`
-- Typical checks:
- - `dotnet format Fory.sln --verify-no-changes`
- - `dotnet build Fory.sln -c Release --no-restore`
- - `dotnet test Fory.sln -c Release`
-
-## C++
-
-- Build/test from repo root or `cpp/`
-- Architecture note: only add `--config=x86_64` on `x86_64` or `amd64`, not on
arm64.
-- Typical checks:
- - `bazel build //cpp/...`
- - `bazel test $(bazel query //cpp/...)`
-
-## Python
-
-- Work from `python/`
-- Typical checks:
- - `ruff format .`
- - `ruff check .`
- - `ENABLE_FORY_CYTHON_SERIALIZATION=0 pytest -v -s .`
- - `ENABLE_FORY_CYTHON_SERIALIZATION=1 pytest -v -s .`
-
-## Rust
-
-- Work from `rust/`
-- Typical checks:
- - `cargo fmt --check`
- - `cargo clippy --all-targets --all-features -- -D warnings`
- - `cargo test --features tests`
-
-## Swift
-
-- Work from `swift/`
-- Typical checks:
- - `swiftlint lint --config .swiftlint.yml`
- - `swift build`
- - `swift test`
-
-## Go
-
-- Work from `go/fory/`
-- Typical checks:
- - `go fmt ./...`
- - `go test -v ./...`
-
-## Xlang Matrix Triggers
-
-When the patch touches xlang behavior, type mapping, protocol bytes,
compatible mode, `TypeMeta`, or cross-language container semantics, require the
relevant Java-driven xlang tests:
-
-- `org.apache.fory.xlang.CPPXlangTest`
-- `org.apache.fory.xlang.CSharpXlangTest`
-- `org.apache.fory.xlang.RustXlangTest`
-- `org.apache.fory.xlang.GoXlangTest`
-- `org.apache.fory.xlang.PythonXlangTest`
-
-If the touched language is Swift and xlang behavior changed, include
`org.apache.fory.xlang.SwiftXlangTest` too.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 797a72ca6..37ca352a9 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -35,9 +35,9 @@
https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-fo
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
-- [ ] If `yes`, my PR description includes the required `ai_review` summary
and screenshot evidence of the final clean AI review results from both fresh
reviewers on the current PR diff or current HEAD after the latest code changes.
+- [ ] If `yes`, my PR description includes the required `ai_review` summary
and screenshot evidence or equivalent persisted links of the final clean AI
review results from both fresh reviewers described in `AI_POLICY.md`, the
Fory-guided reviewer and the independent general reviewer, on the current PR
diff or current HEAD after the latest code changes.
-<!-- If substantial AI assistance = `yes`, paste the completed checklist and
disclosure block here, including the final ai_review summary and screenshot
evidence from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes. -->
+<!-- If substantial AI assistance = `yes`, paste the completed checklist and
disclosure block here, including the final ai_review summary and screenshot
evidence or equivalent persisted links from both fresh reviewers described in
AI_POLICY.md, the Fory-guided reviewer and the independent general reviewer, on
the current PR diff or current HEAD after the latest code changes. -->
## Does this PR introduce any user-facing change?
diff --git a/AGENTS.md b/AGENTS.md
index a1d207b6a..5cd2581d5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,7 +7,7 @@ This is the entry point for AI guidance in Apache Fory. Read
this file first, th
- `.agents/README.md`: routing table for selective loading.
- `.agents/repo-reference.md`: repo layout, architecture, compiler notes, and
key directories.
- `.agents/docs-and-formatting.md`: documentation, specification, and markdown
rules.
-- `.agents/ci-and-pr.md`: CI triage, PR expectations, and commit conventions.
+- `.agents/ci-and-pr.md`: code review workflow, CI triage, PR expectations,
and commit conventions.
- `.agents/testing/integration-tests.md`: `integration_tests/` prerequisites,
regeneration rules, and commands.
- `docs/security/index.md`: security model index.
- `docs/security/threat-model.md`: project-level trust boundaries, non-goals,
@@ -139,6 +139,15 @@ This is the entry point for AI guidance in Apache Fory.
Read this file first, th
- When reviewing a GitHub pull request, always do the review in a new local
git worktree. Do not switch the current branch or reuse the current worktree
for that review unless the user explicitly asks for it.
- Contributors should fork `[email protected]:apache/fory.git`, push code
changes to the fork, and open pull requests from that fork into `apache/fory`.
+## Code Review Expectations
+
+- For Apache Fory PR, branch, commit-range, and local-diff code reviews, load
`.agents/ci-and-pr.md` and follow its review workflow, red flags, and
validation guidance unless explicitly acting as the independent general
reviewer required by `AI_POLICY.md`.
+- When explicitly acting as the independent general reviewer required by
`AI_POLICY.md`, do not load `.agents/ci-and-pr.md` or use copied Fory-specific
review checklist prompts. Still obey review-only safety rules, this carve-out,
and any general instructions required by the reviewer tool.
+- When the task environment supports review subagents, run Fory-guided code
review through a fresh read-only review subagent while the main agent
coordinates scope, checks findings, and reports the final result.
+- Reuse the same review subagent for later review passes on the same feature
unless a workflow explicitly requires a fresh reviewer; use a fresh review
subagent for each different feature.
+- Review-only tasks are read-only: do not create task files, edit files, apply
patches, run tests, run builds, run benchmarks, run linters, install packages,
commit, push, fix tests, or update docs unless the user explicitly starts an
implementation or verification task.
+- Review-only agents keep planning and findings in memory or in the final
review response. They report missing validation evidence instead of running
validation commands themselves.
+
## Shared Validation Expectations
- Run the relevant tests for every touched language or subsystem before
finishing.
diff --git a/AI_POLICY.md b/AI_POLICY.md
index 850189799..5af135f1b 100644
--- a/AI_POLICY.md
+++ b/AI_POLICY.md
@@ -44,7 +44,7 @@ Required disclosure fields:
- Scope of assistance (for example: design drafting, code drafting, refactor
suggestions, tests, docs)
- Affected files or subsystems (high-level)
- AI review summary (self-review completed, AI review loop status, and final
result)
-- Final AI review artifacts (embedded screenshots or links showing the final
clean AI review results from both fresh reviewers on the current PR diff or
current HEAD after the latest code changes)
+- Final AI review artifacts (embedded screenshots or equivalent persisted
links showing the final clean AI review results from both fresh reviewers on
the current PR diff or current HEAD after the latest code changes)
- Human verification performed (checks run locally or in CI, and results
reviewed by the contributor)
- Provenance and license confirmation (see Section 6)
@@ -56,7 +56,7 @@ AI Usage Disclosure
- scope: <design drafting | code drafting | refactor suggestions | tests |
docs | other>
- affected_files_or_subsystems: <high-level paths/modules>
- ai_review: <line-by-line self-review completed; summarize the two-reviewer
loop and final no-further-comments result>
-- ai_review_artifacts: <embedded screenshots or links showing the final clean
review results from both fresh reviewers on the current PR diff or current HEAD
after the latest code changes>
+- ai_review_artifacts: <embedded screenshots or equivalent persisted links
showing the final clean review results from both fresh reviewers on the current
PR diff or current HEAD after the latest code changes>
- human_verification: <checks run locally or in CI + pass/fail summary +
contributor reviewed results>
- performance_verification: <N/A or benchmark/regression evidence summary>
- provenance_license_confirmation: <Apache-2.0-compatible provenance
confirmed; no incompatible third-party code introduced>
@@ -92,17 +92,17 @@ For substantial AI assistance, every PR MUST also provide
verifiable evidence of
- The contributor personally performs a line-by-line self-review first and
fixes all issues found before requesting AI review.
- The contributor then runs two fresh AI review agents on the current PR diff
or current HEAD after the latest code changes:
- - one reviewer MUST use `.claude/skills/fory-code-review/SKILL.md`
- - one reviewer MUST NOT use that skill
+ - one reviewer MUST be a Fory-guided reviewer prompted to follow `AGENTS.md`
and the review workflow in `.agents/ci-and-pr.md`
+ - one reviewer MUST be an independent general reviewer in a separate
clean-context review session; it MAY follow mandatory repository safety and
contribution instructions required by its tooling, but it MUST NOT be pointed
to `.agents/ci-and-pr.md` or any copied Fory-specific review checklist. If its
tooling auto-loads `AGENTS.md`, it MUST follow the independent-review carve-out
there instead of loading `.agents/ci-and-pr.md`.
- The contributor addresses all actionable comments from both reviewers,
reruns both reviewers on the updated diff, and repeats this loop until both
reviewers report no further actionable comments.
-- The PR body MUST include the final clean AI review result from both
reviewers plus screenshot evidence in the `AI Usage Disclosure`.
+- The PR body MUST include the final clean AI review result from both
reviewers plus screenshot evidence or equivalent persisted links in the `AI
Usage Disclosure`.
- If the contributor cannot produce this evidence, the PR is not ready for
maintainer review.
Definitions for AI review evidence:
- Fresh AI review agent means a new clean-context review session started on
the current diff after the latest code changes. Reusing an old reviewer thread
as the final review evidence is not sufficient.
- Final clean AI review result means the last rerun of both reviewers on the
current PR diff or current HEAD, with no unresolved actionable comments
remaining.
-- Screenshot evidence must show, for each reviewer, the reviewer identity or
workflow label, the reviewed diff/commit or PR state, and the clean
no-further-actionable-comments result. Persisted links with equivalent
information MAY be used when screenshots are impractical.
+- Screenshots or equivalent persisted links must show, for each reviewer, the
reviewer identity or workflow label, the reviewed diff/commit or PR state, and
the clean no-further-actionable-comments result.
Definition of adequate human verification:
@@ -150,7 +150,7 @@ Maintainers MAY close or return PRs that materially fail
project standards, incl
- Contributor cannot explain key implementation logic
- Missing required disclosure for substantial AI assistance
-- Missing required AI review loop evidence, final clean reviewer outputs, or
screenshot artifacts in the PR body
+- Missing required AI review loop evidence, final clean reviewer outputs, or
screenshot artifacts or equivalent persisted links in the PR body
- Missing or inadequate human verification evidence for changed behavior
- Redundant implementation of existing utilities without clear necessity
- Introduction of dead code, unused helpers, or placeholder abstractions
without justification
@@ -182,9 +182,9 @@ This is the canonical checklist for the PR template AI
section.
- [ ] If `yes`, I can explain and defend all important changes without AI help.
- [ ] If `yes`, I reviewed AI-assisted code changes line by line before
submission.
- [ ] If `yes`, I completed line-by-line self-review first and fixed issues
before requesting AI review.
-- [ ] If `yes`, I ran two fresh AI review agents on the current PR diff or
current HEAD after the latest code changes: one using
`.claude/skills/fory-code-review/SKILL.md` and one without that skill.
+- [ ] If `yes`, I ran two fresh AI review agents on the current PR diff or
current HEAD after the latest code changes: one Fory-guided reviewer using
`AGENTS.md` and `.agents/ci-and-pr.md`, and one independent general reviewer in
a separate clean-context review session that was not pointed to
`.agents/ci-and-pr.md` or any copied Fory-specific review checklist. If the
independent reviewer's tooling auto-loaded `AGENTS.md`, it followed the
independent-review carve-out there.
- [ ] If `yes`, I addressed all AI review comments and repeated the review
loop until both ai reviewers reported no further actionable comments.
-- [ ] If `yes`, I attached screenshot evidence of the final clean AI review
results from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes in this PR body.
+- [ ] If `yes`, I attached screenshot evidence or equivalent persisted links
of the final clean AI review results from both fresh reviewers on the current
PR diff or current HEAD after the latest code changes in this PR body.
- [ ] If `yes`, I ran adequate human verification and recorded evidence
(checks run locally or in CI, pass/fail summary, and confirmation I reviewed
results).
- [ ] If `yes`, I added/updated tests and specs where required.
- [ ] If `yes`, I validated protocol/performance impacts with evidence when
applicable.
@@ -198,7 +198,7 @@ AI Usage Disclosure
- scope: <design drafting | code drafting | refactor suggestions | tests |
docs | other>
- affected_files_or_subsystems: <high-level paths/modules>
- ai_review: <line-by-line self-review completed; summarize the two-reviewer
loop and final no-further-comments result>
-- ai_review_artifacts: <embedded screenshots or links showing the final clean
review results from both fresh reviewers on the current PR diff or current HEAD
after the latest code changes>
+- ai_review_artifacts: <embedded screenshots or equivalent persisted links
showing the final clean review results from both fresh reviewers on the current
PR diff or current HEAD after the latest code changes>
- human_verification: <checks run locally or in CI + pass/fail summary +
contributor reviewed results>
- performance_verification: <N/A or benchmark/regression evidence summary>
- provenance_license_confirmation: <Apache-2.0-compatible provenance
confirmed; no incompatible third-party code introduced>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2cf1fa02b..6039ea363 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,8 @@ Key points:
- AI tools are allowed as assistants, but contributors remain fully
responsible for all submitted changes.
- AI-assisted code must be reviewed carefully line by line before submission,
and contributors must be able to explain and defend it during review.
-- For substantial AI assistance, contributors must complete a self-review
first, then repeat a two-reviewer AI review loop until both reviewers report no
further actionable comments, and include the final clean review screenshots in
the PR disclosure.
+- For substantial AI assistance, contributors must complete a self-review
first, then repeat a two-reviewer AI review loop on the current PR diff or
current HEAD after the latest code changes until both reviewers report no
further actionable comments. One reviewer must be Fory-guided by `AGENTS.md`
and `.agents/ci-and-pr.md`; the other must be an independent general reviewer
in a separate clean-context session that is not pointed to
`.agents/ci-and-pr.md` or copied Fory-specific review c [...]
+- Include the final clean review screenshots or equivalent persisted links
from both fresh reviewers in the PR disclosure.
- For substantial AI assistance, provide privacy-safe disclosure in the PR
using the [AI Contribution
Checklist](./AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
template. Minor/narrow AI assistance does not require full disclosure.
- Include adequate human verification evidence (for example exact
build/lint/test commands and pass/fail outcomes), and add/update tests and
specs where required.
- For protocol/type-mapping/wire-format or performance-sensitive changes,
provide the required compatibility/performance validation evidence.
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 8fa9fec92..411255a4a 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -129,3 +129,7 @@ npx prettier --write "**/*.md"
## Contributing
For contribution details, see [How to contribute to Apache
Fory™](https://github.com/apache/fory/blob/main/CONTRIBUTING.md).
+For AI-assisted contributions, follow the
+[AI Contribution
Policy](https://github.com/apache/fory/blob/main/AI_POLICY.md), including the
+required self-review, two-reviewer AI review loop, disclosure, and
verification evidence for
+substantial AI assistance.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
