fglock · fglock · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/.gitignore b/.gitignore
@@ -75,6 +75,8 @@ dev/prompts/CONTROL_FLOW_FIX_INSTRUCTIONS.md
 !QUICKSTART.md
 !CONTRIBUTING.md
 !AGENTS.md
+!SECURITY.md
+!AI_POLICY.md
 test_*.log
 test_*.json
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -187,44 +187,7 @@ See `.cognition/skills/` for specialized debugging and development skills:
 - `debug-exiftool` - ExifTool test debugging
 - `profile-perlonjava` - Performance profiling
 
-## Regression Tracking (feature/defer-blocks branch)
-
-### Summary
-
-All reported regressions have been investigated. The issues fall into two categories:
-1. **Fixed in this branch**: goto-related issues
-2. **Pre-existing on master**: MethodHandle conversion errors, regex octal escape parsing
-
-### Regression Status
-
-| Test | Status | Details |
-|------|--------|---------|
-| op/die_goto.t | **FIXED** (5/5) | `goto &sub` in `$SIG{__DIE__}` handlers now works |
-| uni/goto.t | **FIXED** (2/4) | Tests 1-2 pass (goto &{expr}). Tests 3-4 fail due to pre-existing regex octal escape bug |
-| op/bop.t | Pre-existing | MethodHandle conversion error - fails on master too |
-| op/warn.t | Pre-existing | MethodHandle conversion error - fails on master too |
-| re/subst.t | Pre-existing | MethodHandle conversion error - fails on master too |
-| re/pat_rt_report.t | Pre-existing | MethodHandle conversion error - fails on master too |
-| lib/croak.t | Pre-existing | `class` feature incomplete |
-
-### Fixes Applied in This Branch
-
-1. **EmitControlFlow.java**: Added `handleGotoSubroutineBlock()` for `goto &{expr}` tail call support
-2. **CompileOperator.java**: Added `goto &{expr}` support to bytecode interpreter  
-3. **RuntimeControlFlowList.java**: Added validation for undefined subroutines in tail calls
-4. **RuntimeCode.java**: Added `gotoErrorPrefix()` for "Goto undefined subroutine" error messages
-5. **CompileAssignment.java**: Added `vec` lvalue support for interpreter
-6. **OpcodeHandlerExtended.java**: Fixed `|=` and `^=` to use polymorphic `bitwiseOr`/`bitwiseXor`
-7. **WarnDie.java**: Added TAILCALL trampoline for `goto &sub` in `$SIG{__DIE__}` handlers
-
-### Pre-existing Issues (on master too)
-
-- **MethodHandle conversion errors**: Affects op/warn.t, re/subst.t, re/pat_rt_report.t, op/bop.t
-- **Regex octal escapes**: `\345` in patterns is parsed as backreference `\3` + `45`
-- **op/bop.t**: `new version ~$_` crashes in Version.java
-- **String bitwise ops**: Interpreter uses numeric ops instead of string ops
-
-### How to Check Regressions
+## How to Check Regressions
 
 When a unit test fails on a feature branch, always verify whether it also fails on master before trying to fix it:
 

diff --git a/AI_POLICY.md b/AI_POLICY.md
@@ -0,0 +1,139 @@
+# AI-Assisted Development Policy
+
+PerlOnJava uses AI coding assistants as part of its development workflow. This document describes our policy for AI-assisted contributions and the research behind it.
+
+## Table of Contents
+
+### Part 1 — Policy
+
+- [Commit Attribution](#commit-attribution)
+- [Human Responsibility](#human-responsibility)
+- [What Counts as AI-Assisted](#what-counts-as-ai-assisted)
+- [Future Considerations](#future-considerations)
+
+### Part 2 — Research
+
+- [Industry Landscape](#industry-landscape)
+  - [Outright Ban — Gentoo Linux](#1-outright-ban--gentoo-linux)
+  - [Mandatory Attribution — Linux Kernel](#2-mandatory-attribution--linux-kernel)
+  - [Guidelines with Recommended Token — Apache Software Foundation](#3-guidelines-with-recommended-token--apache-software-foundation)
+  - [PR-Level Disclosure — Oh My Zsh](#4-pr-level-disclosure--oh-my-zsh)
+  - [Copyleft and Training Data Concerns — Software Freedom Conservancy](#5-copyleft-and-training-data-concerns--software-freedom-conservancy)
+- [Comparison of Attribution Mechanisms](#comparison-of-attribution-mechanisms)
+- [Key Observations](#key-observations)
+
+---
+
+# Part 1 — Policy
+
+## Commit Attribution
+
+AI-assisted commits include two markers in the commit message:
+
+```
+Generated with [Devin](https://cli.devin.ai/docs)
+
+Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
+```
+
+- **`Generated with`** — identifies the tool and links to its documentation.
+- **`Co-Authored-By`** — a GitHub-recognized trailer that shows the AI tool as a co-author in the commit UI. GitHub renders this as a visible avatar and link on the commit.
+
+As of April 2025, approximately 18% of PerlOnJava commits (~2,250 out of ~12,400) carry a Devin `Co-Authored-By` tag. (These numbers are approximate at time of writing; query with `git log --all --format="%B" | grep -c "Co-[Aa]uthored-[Bb]y.*[Dd]evin"`.)
+
+## Human Responsibility
+
+The human committer reviews all AI-generated code before committing and takes full responsibility for correctness, licensing, and adherence to project standards. AI-assisted commits go through the same PR review process as any other contribution.
+
+Reviewers of AI-assisted contributions should pay particular attention to security-sensitive areas such as `eval`, `system`/`exec`, and Java integration surfaces. See [SECURITY.md](SECURITY.md) for PerlOnJava's security considerations and the specific constructs that require care.
+
+## What Counts as AI-Assisted
+
+A commit is tagged as AI-assisted when an AI tool (Devin, Copilot, Claude, etc.) generated or substantially contributed to the code, commit message, or design in that commit. Minor uses such as autocomplete suggestions or spell-checking do not require attribution.
+
+## Future Considerations
+
+- Define whether PerlOnJava should adopt a more structured trailer (e.g., `Assisted-by:`) in addition to or instead of `Co-Authored-By`.
+- Consider whether model version should be recorded.
+- Review implications for PerlOnJava's license (Artistic License 2.0 / GPL) regarding AI-generated code.
+
+---
+
+# Part 2 — Research
+
+Research conducted in April 2025 across major open-source projects reveals a spectrum of approaches, from outright bans to permissive use with attribution.
+
+## Industry Landscape
+
+### 1. Outright Ban — Gentoo Linux
+
+**Source:** [LWN.net, April 2024](https://lwn.net/Articles/970072/)
+
+The Gentoo Council voted unanimously to ban AI-generated contributions:
+
+> "It is expressly forbidden to contribute to Gentoo any content that has been created with the assistance of Natural Language Processing artificial intelligence tools."
+
+Concerns cited: copyright risk from training data, quality control, and ethics. Enforcement is trust-based; the project acknowledges it cannot detect AI-generated code but sets clear expectations.
+
+### 2. Mandatory Attribution — Linux Kernel
+
+**Source:** [kernel.org `Documentation/process/coding-assistants.rst`](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-assistants.rst)
+
+The Linux kernel requires:
+
+- **AI agents MUST NOT add `Signed-off-by` tags.** Only humans can certify the Developer Certificate of Origin (DCO).
+- **An `Assisted-by:` trailer is required**, in a machine-parseable format:
+  ```
+  Assisted-by: Claude:claude-3-opus coccinelle sparse
+  ```
+  Format: `AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]`
+
+This uses git's trailer system (same as `Signed-off-by`, `Reviewed-by`, `Fixes:`), making it searchable and extractable from git history.
+
+### 3. Guidelines with Recommended Token — Apache Software Foundation
+
+**Source:** [apache.org — ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html)
+
+The ASF permits AI-generated code if contributors ensure:
+
+1. The AI tool's terms do not conflict with the Open Source Definition.
+2. No third-party copyrighted materials are included, or any such materials are compatibly licensed.
+3. Contributors obtain reasonable certainty via tools that flag training-data-similar output.
+
+For attribution, the ASF recommends a `Generated-by:` token in commit messages, designed to be automatically extracted into a machine-readable Tooling-Provenance file for releases.
+
+### 4. PR-Level Disclosure — Oh My Zsh
+
+**Source:** [ohmyzsh PR template](https://github.com/ohmyzsh/ohmyzsh/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
+
+Their PR checklist includes:
+
+> "If I used AI tools (ChatGPT, Claude, Gemini, etc.) to assist with this contribution, I've disclosed it below."
+
+Disclosure is at the PR level rather than per-commit.
+
+### 5. Copyleft and Training Data Concerns — Software Freedom Conservancy
+
+**Source:** [sfconservancy.org, February 2022](https://sfconservancy.org/blog/2022/feb/03/github-copilot-copyleft-gpl/)
+
+The SFC raised concerns about GitHub Copilot being trained on copyleft-licensed code and potentially reproducing it without license compliance. This underpins many projects' caution about AI-generated contributions.
+
+## Comparison of Attribution Mechanisms
+
+| Mechanism | Used by | Machine-parseable | Granularity | Notes |
+|-----------|---------|-------------------|-------------|-------|
+| `Assisted-by:` trailer | Linux kernel | Yes | Per-commit | Includes model version and tools |
+| `Generated-by:` token | Apache (recommended) | Yes | Per-commit | Designed for release provenance files |
+| `Co-Authored-By:` + `Generated with` | PerlOnJava, Devin | Yes | Per-commit | GitHub renders co-author in UI |
+| PR template checkbox | Oh My Zsh | No | Per-PR | Contributor self-disclosure |
+| Outright ban | Gentoo | N/A | N/A | Trust-based enforcement |
+
+## Key Observations
+
+1. **No project has solved detection.** Gentoo, the kernel, and others all acknowledge that enforcement is trust-based. Policies set expectations and enable traceability rather than policing.
+
+2. **`Co-Authored-By` vs `Assisted-by`**: `Co-Authored-By` implies shared authorship and responsibility. The kernel's `Assisted-by` makes it explicit that the human takes full responsibility and the AI was a tool. This distinction matters for DCO/legal purposes in projects that require sign-off.
+
+3. **Model versioning**: The kernel's format captures which model version was used, which is useful for auditing if a model is later found to have training-data issues.
+
+4. **The trend is toward transparency, not prohibition.** Most active projects (outside Gentoo) accept AI-assisted contributions but require clear attribution.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,8 +21,8 @@ git clone https://github.com/fglock/PerlOnJava.git
 cd PerlOnJava
 
 # Build and run tests
-make        # Build + fast unit tests
-make dev    # Force clean rebuild
+make        # Build + run all unit tests
+make dev    # Build only, skip tests (for quick iteration during debugging)
 
 # Run comprehensive tests
 make test-all
@@ -32,18 +32,18 @@ make test-all
 
 **Before making changes:**
 1. Create a feature branch: `git checkout -b feature-name`
-2. Read the [Architecture Guide](docs/reference/architecture.md)
-3. Check [Roadmap](docs/about/roadmap.md) for planned features
+2. **Never push directly to master** — always use feature branches and PRs
+3. Read the [Architecture Guide](docs/reference/architecture.md)
+4. Check [Roadmap](docs/about/roadmap.md) for planned features
 
 **While coding:**
 1. Follow existing code style
 2. Run `make` frequently to ensure tests pass
 3. Add tests for new features in `src/test/resources/unit/`
 
 **Before committing:**
-1. Ensure `make` passes (fast unit tests)
-2. Run `make test-all` for comprehensive testing
-3. Write clear commit messages
+1. Ensure `make` passes (all unit tests)
+2. Write clear commit messages
 
 ### 3. Submit Pull Request
 
@@ -100,15 +100,12 @@ perl5_t/ (at project root)
 ### Building and Testing
 
 ```bash
-# Build with incremental compilation
-make build
+# Build + run all unit tests (default)
+make
 
-# Force clean rebuild (during active development)
+# Build only, skip tests (for quick iteration during debugging)
 make dev
 
-# Run fast unit tests (default)
-make test
-
 # Run all tests including Perl 5 core tests
 make test-all
 
@@ -168,6 +165,8 @@ Developer documentation is in `dev/`:
 - **implementation/** - Implementation notes (regex, tie, overload)
 - **maintenance/** - Maintenance procedures
 
+See also **[AGENTS.md](AGENTS.md)** for detailed testing commands, unimplemented features, environment variables, and git workflow rules.
+
 ## Feature Development
 
 ### Before Adding a Feature
@@ -206,6 +205,10 @@ See **[Module Porting Guide](docs/guides/module-porting.md)** for:
 - **Pull Requests** - Code contributions
 - **Discussions** - Questions and design discussions
 
+## AI-Assisted Contributions
+
+PerlOnJava accepts AI-assisted contributions with proper attribution. See **[AI_POLICY.md](AI_POLICY.md)** for our full policy on commit attribution, human responsibility, and how our approach compares to other open-source projects.
+
 ## Code of Conduct
 
 - Be respectful and constructive

diff --git a/LICENSE.md b/LICENSE.md
@@ -15,10 +15,10 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
 the GNU General Public License or the Artistic License for more details.
 
 You should have received a copy of the Artistic License with this
-Kit, in the file named "[Artistic](Artistic)". If not, I'll be glad to provide one.
+Kit, in the file named "[Artistic License](Artistic)". If not, I'll be glad to provide one.
 
 You should also have received a copy of the GNU General Public License
-along with this program in the file named "[Copying](Copying)". If not, see
+along with this program in the file named "[GPL License](Copying)". If not, see
 <https://www.gnu.org/licenses/>.
 
 ---

diff --git a/Makefile b/Makefile
@@ -196,5 +196,5 @@ sbom-clean:
 check-links:
 	@command -v lychee >/dev/null 2>&1 || { echo "Error: lychee not found. Install with: brew install lychee"; exit 1; }
 	@echo "Checking documentation links..."
-	lychee --offline docs/ dev/design/
+	lychee --offline *.md docs/ dev/design/
 
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -6,7 +6,7 @@ Get PerlOnJava running in 5 minutes.
 
 - **Java Development Kit (JDK) 22 or later**
 - **Git** for cloning the repository
-- **Make** (optional - can use Gradle directly)
+- **Make** (contributors should always use `make`; see [CONTRIBUTING.md](CONTRIBUTING.md))
 
 ### Verify You Have JDK Installed
 
@@ -40,7 +40,7 @@ cd PerlOnJava
 make
 ```
 
-The `make` command compiles the project and runs the fast unit tests. The complete build with tests typically completes in ~30 seconds.
+The `make` command builds the project and runs all unit tests. The complete build with tests typically completes in ~30 seconds.
 
 **Build troubleshooting:**
 

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![Build Status](https://github.com/fglock/PerlOnJava/workflows/Java%20CI%20with%20Gradle/badge.svg)](https://github.com/fglock/PerlOnJava/actions)
 [![License](https://img.shields.io/badge/license-Artistic_1.0_|_GPL_1+-blue.svg)](LICENSE.md)
 
-PerlOnJava compiles Perl to JVM bytecode. One jar file runs on Linux, macOS, and Windows — just add Java 22+.
+PerlOnJava compiles Perl to JVM bytecode — run existing Perl scripts on any platform with a JVM, with access to Java libraries. One jar file runs on Linux, macOS, and Windows — just add Java 22+. PerlOnJava is an independent project, not part of the Perl core distribution.
 
 ## Features
 
@@ -15,7 +15,7 @@ PerlOnJava compiles Perl to JVM bytecode. One jar file runs on Linux, macOS, and
 - **Install more with jcpan** — [pure-Perl CPAN modules](docs/guides/using-cpan-modules.md) work out of the box
 - **JDBC database access** — [PostgreSQL, MySQL, SQLite, Oracle](docs/guides/database-access.md) via standard JDBC drivers
 - **Embed in Java apps** — [JSR-223 ScriptEngine](docs/guides/java-integration.md) integration
-- **Perl 5.42+ features** — [see feature matrix](docs/reference/feature-matrix.md)
+- **Perl 5.42 language compatibility** — [see feature matrix](docs/reference/feature-matrix.md)
 
 ## Quick Start
 
@@ -39,7 +39,7 @@ make
 | [Docker](docs/getting-started/docker.md) | [Using CPAN Modules](docs/guides/using-cpan-modules.md) | [Architecture](docs/reference/architecture.md) |
 | [One-liners](docs/getting-started/oneliners.md) | [Module Porting](docs/guides/module-porting.md) | [Testing](docs/reference/testing.md) |
 
-**About:** [Why PerlOnJava?](docs/about/why-perlonjava.md) | [Roadmap](docs/about/roadmap.md) | [Changelog](docs/about/changelog.md) | [Support](docs/about/support.md)
+**About:** [Why PerlOnJava?](docs/about/why-perlonjava.md) | [Roadmap](docs/about/roadmap.md) | [Changelog](docs/about/changelog.md) | [Support](docs/about/support.md) | [Security](SECURITY.md) | [AI Policy](AI_POLICY.md)
 
 ## About Perl
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -4,6 +4,12 @@
 
 Only the latest release of PerlOnJava receives security fixes. We recommend always running the most recent version.
 
+## Relationship to Perl 5
+
+PerlOnJava is an **independent project** that implements the Perl 5 language on the JVM. It is not part of the Perl core distribution and is not maintained by the Perl core developers. The [Perl security team](https://perldoc.perl.org/perlsecpolicy) (`perl-security@perl.org`) does **not** handle security issues in PerlOnJava — please do not report PerlOnJava vulnerabilities to them.
+
+If you are unsure whether a bug is in PerlOnJava or in Perl itself, report it to PerlOnJava first using the channels below. We will coordinate with the Perl security team if the issue turns out to affect the upstream Perl interpreter.
+
 ## Reporting a Vulnerability
 
 If you discover a security vulnerability in PerlOnJava, please **do not** open a public GitHub issue. Instead, use one of the following private disclosure channels:
@@ -76,6 +82,8 @@ PerlOnJava supports calling Java classes and methods from Perl (JSR-223). This s
 
 PerlOnJava depends on third-party Java libraries and bundles Perl modules. These dependencies may themselves contain vulnerabilities.
 
+**AI-generated code**: AI coding assistants may introduce security-sensitive patterns (e.g., unsanitized input reaching `eval` or `system`, exposed secrets, insecure defaults). All AI-assisted contributions undergo the same review process as human-written code, with particular attention to the risk areas described in this document. See [AI_POLICY.md](AI_POLICY.md) for PerlOnJava's AI-assisted development policy and attribution practices.
+
 **Java dependencies**: Keep your dependencies up to date and monitor them with tools such as [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) or GitHub's Dependabot.
 
 **Bundled Perl modules**: Check the [CPAN Security Advisory Database](https://security.metacpan.org/) and the [CPANSA feed](https://github.com/CPAN-Security/cpansa-feed) for known vulnerabilities in Perl modules.
@@ -93,6 +101,7 @@ Use with vulnerability scanning tools like [OWASP Dependency-Track](https://depe
 - **Disable or restrict Java integration** when it is not needed.
 - **Sanitize all inputs** before they reach any dynamic code execution constructs (`eval`, `system`, `exec`, etc.).
 - **Keep PerlOnJava updated** to the latest release.
+- **Keep your JVM updated** — JVM vulnerabilities affect all PerlOnJava users.
 - **Monitor your Java dependencies** for known CVEs.
 
 ## Out of Scope
@@ -111,7 +120,7 @@ We are grateful to security researchers who responsibly disclose vulnerabilities
 ## Related Resources
 
 - [CPAN Security Group](https://security.metacpan.org/) - CVE Numbering Authority for Perl/CPAN
-- [Perl Security Policy](https://perldoc.perl.org/perlsecpolicy) - Security handling for Perl itself
+- [Perl Security Policy](https://perldoc.perl.org/perlsecpolicy) - Security handling for the Perl core interpreter (independent from PerlOnJava; see [Relationship to Perl 5](#relationship-to-perl-5))
 - [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) - Vulnerability scanner for Java dependencies
 - [GitHub Security Advisories](https://github.com/fglock/PerlOnJava/security/advisories) - Published advisories for this project