docs: present repository as ArchUnitJava product

Author: TristanKruse

.archunitdev/contracts/001-build-baseline/src/test/java/dev/archunitjava/contract/BuildBaselineContractTest.java

@@ -13,8 +13,8 @@ void runsOnThePinnedJavaFeatureRelease() {
     }
 
     @Test
-    void scaffoldDoesNotClaimUnimplementedProductFeatures() {
-        assertEquals("scaffold", ArchUnitJava.status());
-        assertTrue(ArchUnitJava.class.desiredAssertionStatus() || !ArchUnitJava.status().isBlank());
+    void exposesTheExpectedProductNamespace() {
+        assertEquals("dev.archunitjava", ArchUnitJava.class.getPackageName());
+        assertTrue(ArchUnitJava.class.getSimpleName().startsWith("ArchUnit"));
     }
 }

.archunitdev/tasks/001-build-baseline.json

@@ -1,11 +1,11 @@
 {
   "id": "java-001-build-baseline",
   "title": "Foundation: bootstrap a reproducible JDK 25 Maven build",
-  "objective": "Establish the smallest cross-platform build that compiles, tests, and packages the clean-room scaffold reproducibly.",
+  "objective": "Establish the smallest cross-platform build that compiles, tests, and packages the initial ArchUnitJava project reproducibly.",
   "acceptance_criteria": [
     "The Maven Wrapper is pinned with checksum verification and works on Windows and Linux.",
     "JDK and Maven versions are enforced and JUnit runs the smoke contract.",
-    "CI verifies the untouched scaffold without publishing artifacts."
+    "CI verifies the initial project without publishing artifacts."
   ],
   "non_goals": [
     "Do not weaken protected contracts, workflow configuration, or unrelated capabilities.",

AGENTS.md

@@ -2,10 +2,12 @@
 
 ## Purpose
 
-This is a clean-room Java architecture-testing library and an ArchUnitDev2
-workflow proving repository. Implement only the active issue contract. Do not
-copy source code from the upstream ArchUnit project or claim API compatibility
-unless an issue explicitly defines and tests it.
+ArchUnitJava is the Java member of the ArchUnitEverything architecture-testing
+family. This repository is the product repository: implementation, tests,
+documentation, examples, and release artifacts must describe the library, not
+the development workflow used to create it. Implement only the active issue
+contract. Do not copy source code from the upstream ArchUnit project or claim
+API compatibility unless an issue explicitly defines and tests it.
 
 ## Trust boundary
 
@@ -54,4 +56,3 @@ The stable pipeline is `EXTRACT -> PROJECT -> ASSERT -> REPORT`.
 
 Do not weaken tests, change protected contracts, broaden allowed paths, publish
 artifacts, mutate GitHub issues, or merge branches as part of a product issue.
-

README.md

@@ -1,78 +1,99 @@
-# ArchUnitJava Codex proving repository
+# ArchUnitJava
 
-This is a private, clean-room architecture-testing experiment for Java and a
-proving ground for the ArchUnitDev2 coding workflow. It is inspired by the
-ArchUnitEverything family and by the idea of testing architecture as ordinary
-unit tests. It does not copy the upstream ArchUnit implementation and must not
-be represented as the official ArchUnit project.
+Architecture testing for Java.
 
-## Goal
+ArchUnitJava is the Java member of the ArchUnitEverything family, alongside
+[ArchUnitRuby](https://github.com/LukasNiessen/ArchUnitRuby),
+[ArchUnitPython](https://github.com/LukasNiessen/ArchUnitPython), and
+[ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS). It turns compiled Java
+code into a dependency model and lets teams express architectural constraints
+as ordinary JUnit tests.
 
-Build a Java-native library that:
+> **Status:** under active development. The build and product roadmap are in
+> place, but no architecture-analysis API or published artifact is available
+> yet.
 
-- imports compiled Java bytecode without loading or executing target classes;
-- models packages, types, members, dependencies, and JPMS modules as immutable
-  deterministic values;
-- exposes readable architecture rules usable from JUnit;
-- reports every violation with bytecode and source evidence where available;
-- remains useful both issue-by-issue and through a guarded coding campaign.
+## Intended use
 
-The repository begins with 69 dependency-ordered issues. Each issue has a
-human-readable specification under `docs/issues/` and a machine-readable task
-specification under `.archunitdev/tasks/`. An issue is not campaign-ready until
-a separate protected executable contract overlay exists. The issue list is the
-product plan; generated files are review aids, not authority to weaken tests or
-expand scope.
+The public API will make architecture rules read like sentences. The following
+illustrates the intended direction; it is not implemented yet:
 
-## Technical baseline
+```java
+var rule = projectClasses()
+        .inPackage("com.example.api..")
+        .shouldNot()
+        .dependOnClasses()
+        .inPackage("com.example.persistence..");
 
-- JDK 25
-- Java's standard `java.lang.classfile` API (provisional ADR)
-- Maven Wrapper
-- JUnit 6 for this repository's tests
-- no runtime dependencies in the initial core
+assertPasses(rule);
+```
+
+The library is planned to cover:
 
-JDK 25 is an intentional proving-project choice. It gives the extractor the
-standard Class-File API introduced in JDK 24, at the cost of not running on
-older Java installations. That trade-off is recorded in
-`docs/adr/0001-bytecode-backend.md` and must be reassessed before a public
-release.
+- package, class, interface, annotation, record, sealed-type, and member rules;
+- dependencies from declarations, generic signatures, bytecode instructions,
+  annotations, exceptions, lambdas, and method references;
+- cycle, layer, slice, public-interface, inheritance, annotation, and JPMS
+  module policies;
+- JUnit integration, command-line checks, graph reports, CI result formats,
+  baselines, and architecture metrics.
 
-## Pipeline
+## How it works
 
 ```text
-CLASS FILES / JARS
-        |
-        v
-     EXTRACT  -> immutable Java model + dependency evidence
-        |
-        v
-     PROJECT  -> packages, slices, layers, modules, members
-        |
-        v
-      ASSERT  -> typed violations
-        |
-        v
-      REPORT  -> JUnit, CLI, SARIF, JSON, diagrams
+CLASS DIRECTORIES / JARS / MODULES
+                 |
+                 v
+              EXTRACT
+                 |
+                 v
+              PROJECT
+                 |
+                 v
+               ASSERT
+                 |
+                 v
+               REPORT
 ```
 
-Target bytecode is treated as untrusted input. Analysis must never load target
-classes, execute build scripts, initialize classes, or invoke target code.
+ArchUnitJava analyzes compiled class files without loading or executing target
+classes. The initial implementation targets JDK 25 and uses the standard
+`java.lang.classfile` API. This keeps bytecode parsing on the Java platform,
+while the library's own immutable model remains independent of that parser.
+
+Java-specific concerns are product semantics rather than incidental parser
+details. In particular, the implementation must account for:
+
+- erased descriptors and optional generic `Signature` attributes;
+- visible, invisible, parameter, type-use, package, and default annotations;
+- bridge and synthetic members, nested types, anonymous types, and nestmates;
+- records and permitted subclasses of sealed types;
+- bytecode calls, field access, method handles, dynamic constants, and
+  `invokedynamic`;
+- classpath and module-path precedence, duplicate classes, external types,
+  ordinary JARs, modular JARs, and multi-release JARs;
+- JPMS readability, exports, opens, service uses, and service providers.
+
+## Design principles
+
+- The pipeline is `EXTRACT -> PROJECT -> ASSERT -> REPORT`.
+- Rules are immutable values; constructing a rule performs no I/O.
+- Projection and assertion are deterministic in-memory operations.
+- Violations retain structured evidence. Renderers own formatting and escaping.
+- Empty selections fail by default so misspelled scopes cannot silently pass.
+- Analysis never executes target builds, classes, annotation processors,
+  bootstrap methods, or static initializers.
+- Unsupported or incomplete semantics are reported explicitly rather than
+  guessed.
 
-## Repository map
+## Build
 
-- `src/main/java/dev/archunitjava/` — product code
-- `src/test/java/dev/archunitjava/` — executable contracts
-- `docs/RESEARCH.md` — Java and sibling-repository comparison
-- `docs/BACKLOG.md` — dependency-ordered issue map
-- `docs/issues/` — GitHub issue bodies
-- `.archunitdev/tasks/` — machine-readable task specifications
-- `.archunitdev/contracts/` — operator-authored executable overlays (created
-  only when a task is ready to implement)
-- `.archunitdev/profile.toml` — guarded build profile
-- `scripts/generate_backlog_assets.py` — canonical backlog generator
+Requirements:
 
-## Build
+- JDK 25
+- no separate Maven installation; the Maven Wrapper is included
+
+On Linux or macOS:
 
 ```shell
 ./mvnw verify
@@ -84,10 +105,19 @@ On Windows:
 .\mvnw.cmd verify
 ```
 
-The wrapper and a JDK 25 installation are required. CI is the portability
-authority; local Java 8 installations are not sufficient.
+CI verifies the build on Windows and Linux.
+
+## Roadmap
+
+The complete dependency-ordered product backlog is maintained in
+[GitHub Issues](https://github.com/TristanKruse/ArchUnitJava/issues). The local
+[backlog](docs/BACKLOG.md), [Java research](docs/RESEARCH.md), and
+[bytecode-backend decision](docs/adr/0001-bytecode-backend.md) provide the
+technical context behind those issues.
 
-## Current status
+## Relationship to ArchUnit
 
-Repository and backlog scaffolding only. No architecture-analysis capability is
-claimed yet.
+The original [ArchUnit](https://www.archunit.org/) is the established Java
+architecture-testing library. ArchUnitJava is an independent implementation in
+the ArchUnitEverything family. The project does not copy ArchUnit's source code
+or claim drop-in API compatibility.

docs/RESEARCH.md

@@ -2,10 +2,10 @@
 
 ## Product framing
 
-Java already has the mature original ArchUnit. This repository is therefore a
-private workflow experiment and clean-room design exercise, not a claim that
-Java lacks an architecture-testing library. The benchmark is conceptual
-coverage and engineering quality, not compatibility by imitation.
+Java already has the mature original ArchUnit. ArchUnitJava is an independent
+Java member of the ArchUnitEverything family, not a claim that Java lacks an
+architecture-testing library. The benchmark is useful conceptual coverage and
+engineering quality, not compatibility by imitation.
 
 ## What transfers from the sibling libraries
 
@@ -22,12 +22,11 @@ clean-architecture presets, cumulative metrics, a CLI, and CI-oriented result
 formats. TypeScript also demonstrates why path aliases, barrel/public entry
 points, cache semantics, and report filtering need explicit contracts.
 
-The Rust proving backlog contributes workflow lessons: granular task contracts,
-allowed and protected paths, dependency readiness, extraction corpora,
-adversarial inputs, deterministic exports, baselines, and a release decision
-based on evidence. Only its first GitHub product issue was completed; the local
-60-issue expansion remains unfinished and is not evidence of implemented Rust
-features.
+The Rust backlog contributes planning lessons: granular scope, dependency
+readiness, extraction corpora, adversarial inputs, deterministic exports,
+baselines, and a release decision based on evidence. Only its first GitHub
+product issue was completed; its expanded plan is not evidence of implemented
+Rust features.
 
 ## What is genuinely Java-specific
 
@@ -77,4 +76,3 @@ Gradle builds.
   https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/module/ModuleDescriptor.html
 - JUnit User Guide: https://docs.junit.org/current/user-guide/
 - Maven Wrapper: https://maven.apache.org/tools/mavenwrapper.html
-

docs/adr/0001-bytecode-backend.md

@@ -17,7 +17,7 @@ second compatibility calendar.
 
 ## Decision
 
-The proving repository starts on JDK 25 and uses `java.lang.classfile`. Target
+ArchUnitJava starts on JDK 25 and uses `java.lang.classfile`. Target
 classes are parsed as bytes and are never loaded. The domain model must not leak
 JDK parser objects so a later backend can be substituted.
 
@@ -30,4 +30,3 @@ JDK parser objects so a later backend can be substituted.
   importer must bound, catch, and contextualize those failures.
 - A public release must revisit whether Java 17 or 21 compatibility is more
   valuable than the standard API. This ADR does not prejudge that decision.
-

docs/issues/001-build-baseline.md

@@ -1,12 +1,12 @@
 ## Outcome
 
-Establish the smallest cross-platform build that compiles, tests, and packages the clean-room scaffold reproducibly.
+Establish the smallest cross-platform build that compiles, tests, and packages the initial ArchUnitJava project reproducibly.
 
 ## Acceptance criteria
 
 - The Maven Wrapper is pinned with checksum verification and works on Windows and Linux.
 - JDK and Maven versions are enforced and JUnit runs the smoke contract.
-- CI verifies the untouched scaffold without publishing artifacts.
+- CI verifies the initial project without publishing artifacts.
 
 ## Non-goals
 

pom.xml

@@ -7,8 +7,8 @@
   <groupId>dev.archunitjava</groupId>
   <artifactId>archunitjava</artifactId>
   <version>0.0.1-SNAPSHOT</version>
-  <name>ArchUnitJava Codex proving repository</name>
-  <description>Private clean-room architecture-testing workflow experiment for Java</description>
+  <name>ArchUnitJava</name>
+  <description>Architecture testing for Java</description>
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@@ -78,4 +78,3 @@
     </plugins>
   </build>
 </project>
-

scripts/generate_backlog_assets.py

@@ -68,8 +68,8 @@ def item(
 
 ITEMS = (
     item(1, "build-baseline", "Foundation: bootstrap a reproducible JDK 25 Maven build",
-         "Establish the smallest cross-platform build that compiles, tests, and packages the clean-room scaffold reproducibly.", (),
-         ("The Maven Wrapper is pinned with checksum verification and works on Windows and Linux.", "JDK and Maven versions are enforced and JUnit runs the smoke contract.", "CI verifies the untouched scaffold without publishing artifacts."),
+         "Establish the smallest cross-platform build that compiles, tests, and packages the initial ArchUnitJava project reproducibly.", (),
+         ("The Maven Wrapper is pinned with checksum verification and works on Windows and Linux.", "JDK and Maven versions are enforced and JUnit runs the smoke contract.", "CI verifies the initial project without publishing artifacts."),
          ("pom.xml", "mvnw", "mvnw.cmd", ".mvn/**", ".github/workflows/ci.yml", "src/main/java/dev/archunitjava/ArchUnitJava.java", "src/test/java/dev/archunitjava/ArchUnitJavaTest.java"), "foundation", kind="infrastructure", initially_completed=True),
     item(2, "graph-kernel", "Foundation: deterministic Java dependency-graph kernel",
          "Implement stable identifiers, dependency kinds, evidence, nodes, edges, and an immutable deterministic graph.", (1,),

src/main/java/dev/archunitjava/ArchUnitJava.java

@@ -1,12 +1,6 @@
 package dev.archunitjava;
 
-/** Entry point metadata for the proving repository. */
+/** Root namespace for the ArchUnitJava public API. */
 public final class ArchUnitJava {
     private ArchUnitJava() {}
-
-    /** Returns the experimental API status without claiming product capability. */
-    public static String status() {
-        return "scaffold";
-    }
 }
-