@cassiomc1/forgeloop 1.11.1 → 1.13.0

package/ENG/go-development-eng.md

@@ -0,0 +1,103 @@
+---
+name: go-development-eng
+language: en
+description: "Specialist guidance for production Go services, workers, CLIs, modules, and concurrent systems."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: go
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - go-validation
+---
+
+# Go Development Engineering Guide
+
+## Mission and activation
+
+Use this guide for confirmed Go modules and workspaces, services, workers,
+libraries, CLIs, and concurrent systems. ForgeLoop recognizes a valid bounded
+`go.mod`, or a `go.work` that connects to already discovered repository-local
+modules. `.go` source, `go.sum`, vendor metadata, a Docker image, a README, a
+toolchain name, or a `setup-go` CI step alone is insufficient.
+
+Detection parses structure only. It does not invoke `go`, resolve/download
+modules, evaluate build tags, run generators, or execute project code. Go
+workspace and path metadata never trigger new filesystem traversal.
+
+## Authority and precedence
+
+Repository module boundaries, supported Go versions, build tags, target
+matrix, compatibility policy, and release process win over generic advice.
+Use the matching Go specification, standard-library documentation, module and
+workspace documentation, and official Go security guidance after repository
+evidence. The 2026-09 plan snapshot uses Go 1.27/1.27.1 as a current reference;
+that is not permission to upgrade a repository.
+
+Keep the `go` language minimum directive distinct from `toolchain`, the build
+tool's Go version, the release binary's runtime expectations, and the target
+OS/architecture. A newer local toolchain does not change the supported module.
+
+## Modules and workspaces
+
+Keep `module`, `go`, `toolchain`, `require`, `replace`, `exclude`, `retract`,
+`godebug`, `ignore`, and `use` semantics distinct. The bounded `go.mod`
+recognizer accepts valid single and block `ignore` directives as module
+metadata; they do not establish a module by themselves. `go.work` membership
+is accepted only when `use` paths resolve to known discovered local `go.mod`
+files, and `ignore` is not a workspace directive. `replace` and dependency
+metadata are context; ForgeLoop does not perform registry, VCS, version, or
+feature resolution. Preserve nested modules and independent workspace
+ownership in monorepos.
+
+## Architecture and language semantics
+
+Make package ownership, interfaces, zero values, pointer/value choices,
+generics, methods, error wrapping, `panic`/`recover`, `defer`, and resource
+cleanup explicit. Use `errors.Is`/`errors.As` for wrapped errors rather than
+comparing error strings. Keep transport, domain, storage, messaging, and
+subprocess adapters separate where the repository does.
+
+Specify goroutine ownership, cancellation, channel direction and closure,
+bounded worker pools, back pressure, lock ordering, atomics, race behavior,
+deadlines, and graceful shutdown. Avoid goroutine leaks, unbounded creation,
+copying synchronization primitives, deadlocks, and ambiguous channel owners.
+
+## I/O, security, and performance
+
+Bound request, file, decoding, compression, subprocess, queue, and database
+resources. Treat network input, decoded data, module content, subprocess
+output, environment values, and credentials as hostile. Validate before SQL,
+filesystem, templates, deserialization, shell, or external-service calls.
+
+Measure allocation, latency, throughput, queueing, startup, and memory before
+optimizing. Review maps/slices and backing-array retention, pointer lifetimes,
+HTTP timeouts, `net/http` shutdown, `database/sql` pool/transaction policy,
+encoding, and cross-compilation/cgo assumptions.
+
+## Dependencies and build policy
+
+Keep `go.mod`, `go.sum`, vendoring, build tags, cgo flags, generated code,
+licenses, and reproducible build commands under review. Do not treat a module
+download, `go generate`, or a generator's output as routing authority. Keep
+public APIs, error behavior, module compatibility, and toolchain policy
+intentional.
+
+## Verification and Definition of Done
+
+Run focused package tests, table tests, fuzzing, benchmarks, `go vet`, the race
+detector, and `govulncheck` where applicable, followed by repository checks.
+Record exact Go version, module/workspace scope, tags, target, and commands.
+Race-detector or fuzz success covers only exercised paths. Missing tools are
+`NOT_VERIFIED`. ForgeLoop performs bounded structural Go topology analysis, not
+complete module resolution, version solving, build-tag evaluation, or build
+execution.
+
+## Official sources
+
+- [Go language specification](https://go.dev/ref/spec)
+- [Go release history](https://go.dev/doc/devel/release)
+- [Go modules reference](https://go.dev/ref/mod)
+- [Go workspaces](https://go.dev/doc/tutorial/workspaces)
+- [Go standard library](https://pkg.go.dev/std)
+- [Go security policy and tooling](https://go.dev/security/)

package/ENG/java-development-eng.md

@@ -0,0 +1,125 @@
+---
+name: java-development-eng
+language: en
+description: "Specialist guidance for production Java services, libraries, workers, and JVM build systems."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: java
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - java-validation
+---
+
+# Java Development Engineering Guide
+
+## Mission and activation
+
+Use this guide for Java services, libraries, workers, command-line tools, and
+JVM components. ForgeLoop uses owned `.java` source with structural Maven,
+Gradle, or Bazel evidence, an unambiguous Java compiler/platform declaration,
+or a direct `.java` claim. A `pom.xml`, Gradle wrapper/settings file, JDK
+image, generic aggregator, dependency lock, plugin name, or `setup-java` CI
+step alone is not a delivered Java project.
+
+Detection is bounded and static. Maven, Gradle, Bazel, wrappers, plugins,
+annotation processors, tests, Java code, and network resolution are never
+executed. XML DTDs and external entities fail closed.
+
+Gradle `settings.gradle` and `settings.gradle.kts` files contribute topology
+only when top-level, unconditional, quoted `include` arguments connect to
+already discovered Gradle builds. Conditional, interpolated, and dynamic
+expressions remain unresolved. `java-gradle-plugin` is Java evidence because
+it applies Gradle's Java Library plugin. `gradle.properties` is a shared
+configuration surface, not an independent Java project; claims are scoped to
+Gradle builds in its directory while nested independent Gradle settings
+boundaries remain isolated.
+
+## Authority and precedence
+
+Repository architecture, toolchain/build configuration, source/target policy,
+ABI, and supported runtime win over generic advice. Then use the matching Java
+Language Specification/API, official Maven/Gradle/Bazel documentation, and
+version-matched framework documentation. The 2026-09 plan snapshot identifies
+JDK 26 as the current Java SE release and JDK 25 as the latest Oracle LTS;
+neither is an automatic migration target.
+
+Keep separate the JDK running the build tool, Java source level, `--release`,
+bytecode target, compiler toolchain, runtime JRE/JDK, framework minimum,
+vendor distribution, preview features, and target platform.
+
+## Project and build discovery
+
+`pom.xml` is parsed structurally. Owned Java source, compiler properties such
+as `maven.compiler.release`/`source`/`target`, or the compiler plugin can
+confirm Java. A `packaging` value of `pom` with modules is retained as
+aggregator/topology context; the aggregator itself is not classified as a Java
+application without Java evidence. A recognized Gradle `java`,
+`java-library`, `java-platform`, `java-gradle-plugin`, `application`, or `war`
+plugin is static Java build evidence. `java-platform` is intentionally
+source-less Java ecosystem evidence. Literal Bazel `java_library`,
+`java_binary`, `java_test`, `java_import`, and `java_plugin` rules are
+supported. Generic wrappers, settings, and dependency metadata alone remain
+insufficient.
+
+Resolve only bounded, owned metadata. Do not run convention plugins, evaluate
+profiles, follow arbitrary build logic, or recreate the dependency resolver.
+
+## Architecture and language semantics
+
+Keep transport, application, domain, persistence, messaging, and platform
+adapters separate where the repository does. Make thread safety, ownership,
+cancellation, timeouts, resource closure, class loading, reflection, and
+serialization boundaries explicit. Review nullability, generics, variance,
+records, sealed types, pattern matching, immutability, equality/hash contracts,
+exception causes, class initialization, and API/binary compatibility.
+
+Use a deliberate error model: preserve causes, distinguish retryable from
+terminal failures, and avoid exposing credentials, SQL, stack traces, or
+internal paths. Do not make checked/unchecked exception changes incidental.
+
+## Concurrency, I/O, and security
+
+Specify executor ownership, bounded queues, interruption, cancellation,
+deadlines, back pressure, lock ordering, atomics, and shutdown. Avoid blocking
+unknown work on shared pools. Bound request, file, decompression, serialization,
+and database resources. Validate input before reflection, templates, SQL,
+filesystem, process, deserialization, or network use; keep secrets out of
+logs and error responses.
+
+## Performance and portability
+
+Measure allocation, garbage collection, startup, heap, thread, queue, I/O,
+latency, and throughput changes with representative profiles or benchmarks.
+Keep locale, charset, timezone, filesystem, native library, container, CPU, and
+JVM assumptions explicit. Do not use a newer JDK's availability to silently
+change source, bytecode, or runtime requirements.
+
+## Dependencies, frameworks, and interop
+
+Keep Maven/Gradle/Bazel files, lock/dependency policy, generated sources, and
+reproducible build metadata under review. Spring, Quarkus, Micronaut, Jakarta,
+Kotlin, SQL, JNI, and deployment platforms are contextual overlays, not public
+ForgeLoop framework IDs. At JNI/FFI boundaries specify ownership, layout,
+encoding, exceptions, thread attachment, and lifetime. Treat generated and
+vendored code as dependency boundaries.
+
+## Verification and Definition of Done
+
+Run focused module compilation, unit/integration tests, static analysis,
+dependency/security checks, and packaging for the exact JDK, profile, module,
+and target. Check cancellation, timeout, malformed input, resource cleanup,
+compatibility, and observability. Record unavailable tools as `NOT_VERIFIED`.
+ForgeLoop performs bounded structural JVM project analysis, not complete
+Maven/Gradle/Bazel resolution, profile evaluation, dependency solving, or build
+execution.
+
+## Official sources
+
+- [Java SE and JDK documentation](https://docs.oracle.com/en/java/)
+- [Java Language Specification](https://docs.oracle.com/javase/specs/)
+- [Maven POM reference](https://maven.apache.org/pom.html)
+- [Maven compiler plugin](https://maven.apache.org/plugins/maven-compiler-plugin/)
+- [Gradle Java plugin](https://docs.gradle.org/current/userguide/java_plugin.html)
+- [Gradle Java Platform plugin](https://docs.gradle.org/current/userguide/java_platform_plugin.html)
+- [Bazel Java rules](https://bazel.build/reference/be/java)