Merge pull request #96 from wphillipmoore/release/1.1.1

release: 1.1.1

Author: wphillipmoore

.github/workflows/docs.yml

@@ -70,6 +70,7 @@ jobs:
         run: |
           if [ -n "${{ steps.version.outputs.alias }}" ]; then
             mike deploy -F docs/site/mkdocs.yml --push --update-aliases ${{ steps.version.outputs.version }} ${{ steps.version.outputs.alias }}
+            mike set-default -F docs/site/mkdocs.yml --push latest
           else
             mike deploy -F docs/site/mkdocs.yml --push ${{ steps.version.outputs.version }}
           fi

CLAUDE.md

@@ -2,248 +2,130 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Documentation Strategy
-
-This repository uses two complementary approaches for AI agent guidance:
-
-- **AGENTS.md**: Generic AI agent instructions using include directives to force documentation indexing. Contains canonical standards references, shared skills loading, and user override support.
-- **CLAUDE.md** (this file): Claude Code-specific guidance with prescriptive commands, architecture details, and development workflows optimized for `/init`.
-
-### Integration Approach
-
-**For Claude Code** (`/init` command):
-1. Read CLAUDE.md (this file) first for optimized quick-start guidance
-2. Process include directives to load repository standards
-3. Reference AGENTS.md for shared skills and canonical standards location
-4. Apply layered standards: canonical → project-specific → user overrides
-
-**For other AI agents** (Codex, generic LLMs):
-1. Read AGENTS.md first as the primary entry point
-2. Process include directives to load all referenced documentation
-3. Resolve canonical standards repo path (local or GitHub)
-4. Load shared skills from standards repo
-5. Apply user overrides from `~/AGENTS.md` if present
-
-**Key differences**:
-- **CLAUDE.md**: Prescriptive, command-focused, optimized for `/init`
-- **AGENTS.md**: Declarative, include-directive-driven, forces full documentation indexing
-
-Both files share the same underlying standards via include directives, ensuring consistency across all AI agents working in this repository.
-
-### Best Practices for Dual-File Approach
-
-**What goes in AGENTS.md**:
-- Include directives for documentation indexing
-- Canonical standards repository references
-- Shared skills loading instructions
-- User override mechanisms
-- Minimal, declarative content
-
-**What goes in CLAUDE.md**:
-- Claude Code-specific quick-start commands
-- Detailed architecture and design patterns
-- Implementation notes and common workflows
-- Integration guidance between the two files
-- More verbose, prescriptive content
-
-**What goes in neither (use includes instead)**:
-- Repository standards (keep in `docs/repository-standards.md`)
-- Canonical standards (reference external repo)
-- Project-specific conventions (keep in referenced docs)
-
-**Maintenance strategy**:
-- Update standards in source files, not in AGENTS.md or CLAUDE.md
-- Use include directives to pull in shared content
-- Keep AGENTS.md minimal and CLAUDE.md focused on Claude Code workflows
-- Test both entry points when updating documentation structure
-
 <!-- include: docs/standards-and-conventions.md -->
 <!-- include: docs/repository-standards.md -->
 
 ## Project Overview
 
-This is a Java port of `pymqrest`, providing a Java wrapper for the IBM MQ administrative REST API. The project will provide a Java mapping layer for MQ REST API attribute translations and command metadata.
-
-**Project name**: mq-rest-admin
-
-**Status**: Pre-alpha (initial setup)
+Java wrapper for the IBM MQ administrative REST API, ported from `pymqrest` (Python). Provides method-per-command API (`displayQueue()`, `defineQlocal()`, etc.) with attribute mapping between snake_case and MQSC parameter names.
 
-**Build coordinates**: `io.github.wphillipmoore:mq-rest-admin:0.1.0-SNAPSHOT`
+**Build coordinates**: `io.github.wphillipmoore:mq-rest-admin:1.1.1`
 
 **Java package**: `io.github.wphillipmoore.mq.rest.admin`
 
-**Canonical Standards**: This repository follows standards at https://github.com/wphillipmoore/standards-and-conventions (local path: `../standards-and-conventions` if available)
+**Canonical Standards**: https://github.com/wphillipmoore/standards-and-conventions (local: `../standards-and-conventions`)
+
+**Reference implementation**: `../mq-rest-admin-python`
 
 ## Development Commands
 
-### Environment Setup
+### Environment
 
 - **Java**: 17+ (install via `brew install openjdk@17` or SDKMAN)
 - **Maven**: Provided by Maven Wrapper (`./mvnw`), no separate install needed
 
-### Build
-
-```bash
-./mvnw compile          # Compile sources
-./mvnw clean            # Remove target/
-./mvnw clean compile    # Clean rebuild
-./mvnw package          # Compile and package JAR
-```
-
-### Validation
-
-```bash
-./mvnw verify              # Run entire validation pipeline (single command)
-```
-
-The `verify` lifecycle runs in order: formatting check (Spotless) → style check
-(Checkstyle) → compile → unit tests (Surefire) → integration tests (Failsafe) →
-coverage enforcement (JaCoCo 100% line + branch) → bug analysis (SpotBugs) →
-code smell detection (PMD).
-
-Individual tools can also be run standalone:
+### Build and Validate
 
 ```bash
-./mvnw spotless:check      # Check formatting
-./mvnw spotless:apply      # Auto-format code
-./mvnw checkstyle:check    # Check style rules
-./mvnw spotbugs:check      # Check for bug patterns
-./mvnw pmd:check           # Check for code smells
+./mvnw compile              # Compile sources
+./mvnw verify               # Full pipeline: Spotless → Checkstyle → compile → unit tests →
+                            # integration tests → JaCoCo (100% line+branch) → SpotBugs → PMD
+./mvnw spotless:apply       # Auto-format code (run before committing)
 ```
 
 ### Testing
 
 ```bash
-./mvnw test                # Unit tests only (*Test.java)
-./mvnw verify              # Unit + integration tests (*IT.java)
+./mvnw test                                        # All unit tests (*Test.java)
+./mvnw test -Dtest=MqRestSessionTest               # Single test class
+./mvnw test -Dtest="MqRestSessionTest#testMethod"  # Single test method
+./mvnw verify                                      # Unit + integration tests (*IT.java)
 ```
 
 - **Framework**: JUnit 5 (Jupiter)
 - **Mocking**: Mockito 5 with `@ExtendWith(MockitoExtension.class)`
 - **Assertions**: AssertJ (`assertThat(x).isEqualTo(y)`)
 - **Coverage**: JaCoCo — 100% line and branch coverage enforced at BUNDLE level
 
-### Linting and Formatting
-
-- **Formatter**: Spotless + google-java-format (2-space indent, opinionated)
-- **Style**: Checkstyle with `google_checks.xml` (bundled)
-- **Bug analysis**: SpotBugs (`effort=Max`, `threshold=Low`)
-- **Code smells**: PMD (default ruleset)
-
-Run `./mvnw spotless:apply` to auto-format before committing.
-
-## Architecture
-
-Direct port of `pymqrest`'s architecture, adapted to Java idioms.
-
-### Technology Stack
-
-- **HTTP client**: `java.net.http.HttpClient` (JDK built-in, zero runtime dependencies)
-- **JSON library**: Gson (`com.google.code.gson:gson`, single JAR, zero transitive deps)
-- **Runtime dependencies**: 1 (Gson ~280KB)
+### Individual Lint Tools
 
-### API Surface
+```bash
+./mvnw spotless:check      # Check formatting (google-java-format, 2-space indent)
+./mvnw checkstyle:check    # Check style (google_checks.xml)
+./mvnw spotbugs:check      # Bug patterns (effort=Max, threshold=Low)
+./mvnw pmd:check           # Code smell detection
+```
 
-- **Style**: Method-per-command mirroring pymqrest (`displayQueue()`, `defineQlocal()`, etc.)
-- **Parameters/results**: `Map<String, Object>` for MQ attributes (dynamic attribute sets, permissive mode)
-- **Fixed-schema types**: Java records for `TransportResponse`, `SyncConfig`, `SyncResult`, `EnsureResult`, `MappingIssue`, credential types
-- **Credentials**: Sealed interface (`Credentials permits BasicAuth, LtpaAuth, CertificateAuth`)
-- **Session**: Single `MqRestSession` class (no mixin decomposition)
+## Git Conventions
 
-### Transport Layer
+### Pre-flight Checklist
 
-- `MqRestTransport` interface (mirrors pymqrest's Protocol) — enables Mockito-based testing
-- `HttpClientTransport` implementation behind that interface
-- Supports TLS/mTLS via `SSLContext`, timeouts via `Duration`, custom headers
+1. Check current branch: `git status -sb`
+2. If on `develop` or `main`, create a `feature/*`, `bugfix/*`, or `hotfix/*` branch first
+3. Enable git hooks: `git config core.hooksPath scripts/git-hooks`
 
-### Attribute Mapping
+### Branching Model (`library-release`)
 
-- Direct port of pymqrest's 3-layer pipeline: key map, value map, key-value map
-- Two directions: request and response
-- Strict/permissive modes with `MappingIssue` tracking
-- Mapping data stored as JSON resource file in `src/main/resources/` (loaded by Gson)
-- Override mechanism with merge/replace modes
+- **`develop`**: Integration branch — PRs target here (squash merge)
+- **`main`**: Release branch — release PRs merge here (regular merge)
+- Allowed branch prefixes: `feature/*`, `bugfix/*`, `hotfix/*`
 
-### Exception Hierarchy
+### Commit Message Rules (enforced by hooks)
 
-Unchecked (`RuntimeException`), sealed:
+Conventional Commits format required:
 
 ```
-MqRestException (sealed, extends RuntimeException)
-├── MqRestTransportException   (network/connection failures)
-├── MqRestResponseException    (malformed JSON, unexpected structure)
-├── MqRestAuthException        (authentication/authorization failures)
-├── MqRestCommandException     (MQSC command returned error codes)
-└── MqRestTimeoutException     (polling timeout exceeded)
-
-MappingException (separate hierarchy, data-transformation errors)
-```
-
-### Package Structure
+<type>(optional-scope): <description>
 
-```
-io.github.wphillipmoore.mq.rest.admin
-    MqRestSession, MqRestTransport, HttpClientTransport, TransportResponse
-io.github.wphillipmoore.mq.rest.admin.auth
-    Credentials, BasicAuth, LtpaAuth, CertificateAuth
-io.github.wphillipmoore.mq.rest.admin.exception
-    MqRestException, MqRest{Transport,Response,Auth,Command,Timeout}Exception
-io.github.wphillipmoore.mq.rest.admin.mapping
-    AttributeMapper, MappingData, MappingIssue, MappingException, MappingOverrideMode
-io.github.wphillipmoore.mq.rest.admin.sync
-    SyncConfig, SyncResult, SyncOperation
-io.github.wphillipmoore.mq.rest.admin.ensure
-    EnsureResult, EnsureAction
+Co-Authored-By: wphillipmoore-claude <255925739+wphillipmoore-claude@users.noreply.github.com>
 ```
 
-## Repository Standards Quick Reference
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
-The include directives at the top of this file load the full repository standards. Key highlights for quick reference:
+The co-author hook validates trailers against approved identities in `docs/repository-standards.md`. Only use the approved co-author lines listed there.
 
-**Pre-flight Checklist**:
-- Check current branch: `git status -sb`
-- If on `develop`, create `feature/*` branch or get explicit approval
-- Enable git hooks: `git config core.hooksPath scripts/git-hooks`
-
-See `docs/repository-standards.md` for complete details.
-
-## Documentation Indexing Strategy
+## Architecture
 
-This repository uses `<!-- include: path/to/file.md -->` directives to force documentation indexing. When you encounter these directives:
+Direct port of pymqrest's architecture, adapted to Java idioms.
 
-1. **Read the referenced files** to understand the full context
-2. **Apply layered standards** in order:
-   - Canonical standards (from `standards-and-conventions` repo)
-   - Project-specific standards (`docs/repository-standards.md`)
-   - User overrides (`~/AGENTS.md` if present)
-3. **Load shared skills** from `<standards-repo-path>/skills/**/SKILL.md`
+### Key Design Decisions
 
-The include directives appear in:
-- `AGENTS.md` - Includes repository standards and conventions
-- `CLAUDE.md` - Includes same standards for Claude Code
-- `docs/standards-and-conventions.md` - Includes canonical standards reference
+- **Zero runtime deps** beyond Gson (~280KB) — HTTP via `java.net.http.HttpClient`
+- **Sealed types**: `MqRestException` hierarchy (unchecked) and `Credentials` interface
+- **Nullability**: JSpecify `@Nullable` annotations; Error Prone + NullAway enforced on JDK 21+ (auto-activated `error-prone` profile)
+- **Dynamic attributes**: `Map<String, Object>` for MQ attributes; Java records for fixed-schema types (`TransportResponse`, `SyncConfig`, `SyncResult`, `EnsureResult`, `MappingIssue`)
+- **Testability**: `MqRestTransport` interface enables Mockito-based testing without HTTP
 
-This approach ensures all AI agents (Codex, Claude, etc.) have access to the same foundational documentation.
+### Attribute Mapping Pipeline
 
-## Documentation Structure
+3-layer pipeline (key map → value map → key-value map) with request/response directions. Strict mode throws `MappingException`; permissive mode records `MappingIssue` entries. Mapping data in `src/main/resources/.../mapping/mapping-data.json`.
 
-- `README.md` - Project overview and quick start
-- `AGENTS.md` - Generic AI agent instructions with include directives
-- `CLAUDE.md` - This file, Claude Code-specific guidance
-- `docs/repository-standards.md` - Project-specific standards (included from AGENTS.md)
-- `docs/standards-and-conventions.md` - Canonical standards reference (includes external repo)
+### Exception Hierarchy
 
-## Key References
+```
+MqRestException (sealed, RuntimeException)
+├── MqRestTransportException   (network/connection)
+├── MqRestResponseException    (malformed JSON)
+├── MqRestAuthException        (auth failures)
+├── MqRestCommandException     (MQSC errors)
+└── MqRestTimeoutException     (polling timeout)
+
+MappingException (separate, data-transformation errors)
+```
 
-**Canonical Standards**: https://github.com/wphillipmoore/standards-and-conventions
-- Local path (preferred): `../standards-and-conventions`
-- Load all skills from: `<standards-repo-path>/skills/**/SKILL.md`
+### Package Layout
 
-**Reference implementation**: `../mq-rest-admin-python` (Python version)
+```
+.admin          — MqRestSession (Builder pattern), MqRestTransport, HttpClientTransport, TransportResponse
+.admin.auth     — Credentials (sealed), BasicAuth, LtpaAuth, CertificateAuth
+.admin.exception — Sealed exception hierarchy
+.admin.mapping  — AttributeMapper, MappingData, MappingIssue, MappingDirection, MappingOverrideMode
+.admin.sync     — SyncConfig, SyncResult, SyncOperation
+.admin.ensure   — EnsureResult, EnsureAction
+```
 
-**External Documentation**:
-- IBM MQ 9.4 administrative REST API
-- MQSC command reference
-- PCF command formats
+## Documentation and Standards
 
-**User Overrides**: `~/AGENTS.md` (optional, applied if present and readable)
+- `AGENTS.md` — Generic AI agent instructions with include directives
+- `docs/repository-standards.md` — Project-specific standards (branching, co-authors, naming)
+- `docs/standards-and-conventions.md` — Canonical standards reference

pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>io.github.wphillipmoore</groupId>
     <artifactId>mq-rest-admin</artifactId>
-    <version>1.1.0</version>
+    <version>1.1.1</version>
     <packaging>jar</packaging>
 
     <name>mq-rest-admin</name>

scripts/git-hooks/pre-commit

@@ -12,7 +12,7 @@ fi
 
 # Block commits to protected branches (universal set — safe for all models).
 case "$current_branch" in
-  develop|release|main|release/*)
+  develop|release|main)
     echo "ERROR: direct commits to protected branches are forbidden ($current_branch)." >&2
     echo "Create a short-lived branch and open a PR." >&2
     exit 1
@@ -44,8 +44,8 @@ case "$branching_model" in
     allowed_display="feature/*, bugfix/*, hotfix/*, or promotion/*"
     ;;
   library-release)
-    allowed_regex='^(feature|bugfix|hotfix)/'
-    allowed_display="feature/*, bugfix/*, or hotfix/*"
+    allowed_regex='^(feature|bugfix|hotfix|release)/'
+    allowed_display="feature/*, bugfix/*, hotfix/*, or release/*"
     ;;
   "")
     echo "WARNING: branching_model not found in $profile_file; falling back to feature/*/bugfix/*." >&2