docs: sync Swift package maintainer guidance (#18)

Author: gaelic-ghost

.github/workflows/validate-repo-maintenance.yml

@@ -0,0 +1,21 @@
+name: Validate Repo Maintenance
+
+# Branch protection should require the Actions check context `validate`.
+# GitHub exposes the job check run by this job name, not by the workflow title.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    name: validate
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Swift repo-maintenance tools
+        run: brew install swiftformat swiftlint
+      - name: Run repo-maintenance validation
+        run: bash scripts/repo-maintenance/validate-all.sh

.swiftformat

@@ -0,0 +1,92 @@
+# Exported from Gale's SwiftFormat for Xcode settings and curated for repo use.
+# This file is the repository source of truth for formatting. If the host app
+# configuration changes later, re-export from the shared SwiftFormat settings
+# and review the diff before importing it back into the app.
+
+--rules andOperator,anyObjectProtocol,applicationMain,assertionFailures,blankLineAfterImports,blankLinesAfterGuardStatements,blankLinesAroundMark,blankLinesAtEndOfScope,blankLinesAtStartOfScope,blankLinesBetweenChainedFunctions,blankLinesBetweenImports,blankLinesBetweenScopes,braces,conditionalAssignment,consecutiveBlankLines,consecutiveSpaces,consistentSwitchCaseSpacing,docComments,docCommentsBeforeModifiers,duplicateImports,elseOnSameLine,emptyBraces,emptyExtensions,enumNamespaces,environmentEntry,extensionAccessControl,fileMacro,genericExtensions,headerFileName,hoistAwait,hoistPatternLet,hoistTry,indent,initCoderUnavailable,isEmpty,leadingDelimiters,linebreakAtEndOfFile,linebreaks,modifierOrder,noForceTryInTests,noForceUnwrapInTests,noGuardInTests,numberFormatting,opaqueGenericParameters,organizeDeclarations,preferFinalClasses,privateStateVariables,redundantAsync,redundantBackticks,redundantBreak,redundantClosure,redundantEquatable,redundantExtensionACL,redundantFileprivate,redundantGet,redundantInit,redundantInternal,redundantLet,redundantLetError,redundantMemberwiseInit,redundantNilInit,redundantObjc,redundantOptionalBinding,redundantParens,redundantPattern,redundantPublic,redundantRawValues,redundantReturn,redundantSelf,redundantSendable,redundantStaticSelf,redundantSwiftTestingSuite,redundantThrows,redundantType,redundantTypedThrows,redundantVariable,redundantViewBuilder,semicolons,simplifyGenericConstraints,sortDeclarations,sortImports,sortTypealiases,spaceAroundBraces,spaceAroundBrackets,spaceAroundComments,spaceAroundGenerics,spaceAroundOperators,spaceAroundParens,spaceInsideBrackets,spaceInsideComments,spaceInsideGenerics,spaceInsideParens,strongOutlets,strongifiedSelf,swiftTestingTestCaseNames,todos,trailingClosures,trailingCommas,trailingSpace,typeSugar,validateTestCases,void,wrap,wrapArguments,wrapAttributes,wrapLoopBodies,wrapMultilineFunctionChains,wrapSingleLineComments,yodaConditions
+
+--acronyms ID,URL,UUID
+--allow-partial-wrapping true
+--anonymous-for-each convert
+--asset-literals visual-width
+--binary-grouping 4,8
+--line-between-guards false
+--category-mark "MARK: %c"
+--class-threshold 0
+--closing-paren balanced
+--closure-void remove
+--complex-attributes preserve
+--computed-var-attributes preserve
+--conditional-assignment after-property
+--date-format system
+--decimal-grouping 3,6
+--doc-comments before-declarations
+--else-position same-line
+--empty-braces no-space
+--enum-namespaces always
+--equatable-macro none
+--exponent-case lowercase
+--extension-acl on-extension
+--file-macro "#file"
+--func-attributes preserve
+--group-blank-lines true
+--guard-else auto
+--header ignore
+--hex-grouping 4,8
+--hex-literal-case uppercase
+--ifdef outdent
+--import-grouping alpha,access-control
+--indent 4
+--indent-case true
+--indent-strings false
+--inferred-types always
+--init-coder-nil false
+--line-after-marks true
+--linebreaks lf
+--mark-categories false
+--mark-class-threshold 40
+--mark-enum-threshold 40
+--mark-extension-threshold 40
+--mark-struct-threshold 40
+--max-width none
+--operator-func spaced
+--organization-mode type
+--organize-types actor,class,enum,struct
+--pattern-let hoist
+--prefer-synthesized-init-for-internal-structs never
+--property-types infer-locals-only
+--ranges no-space
+--redundant-async tests-only
+--redundant-throws tests-only
+--self remove
+--semicolons inline-only
+--short-optionals preserve-struct-inits
+--smart-tabs enabled
+--some-any true
+--sort-swiftui-properties alphabetize
+--stored-var-attributes preserve
+--struct-threshold 40
+--strip-unused-args always
+--suite-name-format standard-identifiers
+--test-case-name-format raw-identifiers
+--timezone system
+--trailing-commas always
+--trim-whitespace always
+--type-attributes preserve
+--type-blank-lines remove
+--type-body-marks preserve
+--type-delimiter space-after
+--class-threshold 40
+--enum-threshold 40
+--extension-threshold 40
+--void-type Void
+--wrap-arguments preserve
+--wrap-collections preserve
+--wrap-conditions preserve
+--wrap-effects preserve
+--wrap-return-type preserve
+--wrap-string-interpolation default
+--wrap-ternary default
+--wrap-type-aliases preserve
+--xcode-indentation disabled
+--yoda-swap always

.swiftlint.yml

@@ -0,0 +1,20 @@
+# Keep SwiftLint focused on non-formatting checks.
+# SwiftFormat owns visual shape in this repository.
+
+excluded:
+  - .build
+  - .local
+
+only_rules:
+  - duplicate_imports
+  - empty_count
+  - fatal_error_message
+  - force_try
+  - force_unwrapping
+  - unused_import
+
+force_try:
+  severity: warning
+
+force_unwrapping:
+  severity: warning

AGENTS.md

@@ -1,45 +1,159 @@
 # AGENTS.md
 
-## Repository Expectations
+Repo-local guidance for maintaining SwiftASB, a Swift Package Manager library that wraps the local Codex app-server for Swift and SwiftUI clients.
+
+## Repository Scope
+
+### What This File Covers
+
+- Use this file for all work at the SwiftASB repository root.
+- Treat this package as a library first: public API should be deliberate, documented, and tested.
+- Use Swift Package Manager as the source of truth for package structure, dependencies, products, targets, resources, and Swift language mode.
+- Treat the bundled Codex app-server v2 schema as the primary generated-wire source of truth.
+- Treat the generated wire layer as internal scaffolding, not the final public Swift API.
+
+### Where To Look First
+
+- Start with `Package.swift` for package graph, target, dependency, platform, and Swift language mode changes.
+- Use `Sources/SwiftASB/Public/` for public API shape and `Sources/SwiftASB/Protocol/`, `Sources/SwiftASB/Transport/`, and `Sources/SwiftASB/History/` for the main internal runtime surfaces.
+- Use `Sources/SwiftASB/Generated/CodexWire/Latest/` for the promoted generated v2 wire snapshot.
+- Use `Tests/SwiftASBTests/` for Swift Testing coverage.
+- Use `scripts/generate-wire-types.sh` for Codex schema-derived wire refreshes.
+- Use `scripts/repo-maintenance/` for repo-owned validation, shared sync, and release entrypoints.
+- Use `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, and `docs/maintainers/` for shipped behavior, contributor workflow, planned work, and durable design decisions.
+
+## Working Rules
+
+### Change Scope
+
+- Prefer the simplest correct Swift that is easiest to read, reason about, and maintain.
+- Prefer value types for domain modeling.
+- Prefer concrete types internally and reserve protocols for real seams.
+- Mark classes `final` by default when reference semantics are required.
+- Keep dependency flow unidirectional and ownership obvious.
+- Prefer explicit, consistent, and unambiguous names.
+- Prefer synthesized conformances and memberwise initialization whenever they satisfy the real need.
+- Avoid ceremony, wrappers, or extra abstraction layers unless they solve a concrete package problem.
+- Keep operator-facing errors, warnings, and log strings descriptive and human-readable.
+
+### Source of Truth
 
-- Use Swift Package Manager as the source of truth for package structure and dependencies.
 - Prefer `swift package` CLI commands for structural changes whenever the command exists.
 - Use `swift package add-dependency` to add dependencies instead of hand-editing package graphs.
 - Use `swift package add-target` to add library, executable, or test targets.
 - For package configuration not covered by CLI commands, update `Package.swift` intentionally and keep edits minimal.
 - Keep package graph updates together in the same change when structure changes.
-- Validate package changes with:
-  - `swift build`
-  - `swift test`
+- Keep `Package.swift` explicit about its package-wide Swift language mode; prefer `swiftLanguageModes: [.v6]` on current Swift 6-era manifests.
+- Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
+- Keep package resources under the owning target tree, declare them intentionally, and load bundled resources through `Bundle.module`.
 
-## Swift Package Workflow
+### Communication and Escalation
 
+- For Swift, Apple-framework, Apple-platform, or Xcode-related tasks, read the relevant Apple or Swift documentation first before proposing or making changes.
+- If a public API change, generated-wire promotion, new dependency, or ownership change starts widening beyond the requested scope, surface that before implementing it.
+- If SwiftPM guidance drifts, use `sync-swift-package-guidance` to refresh or merge the package workflow baseline.
 - Use `bootstrap-swift-package` only when a new Swift package repo still needs to be created from scratch.
-- Use `sync-swift-package-guidance` when repo guidance for this package drifts and needs to be refreshed or merged forward.
-- Re-run `sync-swift-package-guidance` after substantial package-workflow or plugin updates so local guidance stays aligned.
 - Use `swift-package-build-run-workflow` for manifest, dependency, resource, build, and run work when `Package.swift` is the source of truth.
 - Use `swift-package-testing-workflow` for Swift Testing, XCTest holdouts, fixtures, package test diagnosis, and package test-plan work.
 - Prefer `xcode-build-run-workflow` or `xcode-testing-workflow` only when package work needs Xcode-managed SDK, toolchain, DocC, or test behavior.
-- Keep `Package.swift` explicit about its package-wide Swift language mode; prefer `swiftLanguageModes: [.v6]` on current Swift 6-era manifests.
-- Treat `Package.resolved` and similar package-manager outputs as generated files; do not hand-edit them.
-- Keep package resources under the owning target tree, declare them intentionally, and load bundled resources through `Bundle.module`.
+- Re-run `sync-swift-package-guidance` after substantial package-workflow or plugin updates so local guidance stays aligned.
 
-## Swift Baseline
+## Commands
 
-- For Swift, Apple-framework, Apple-platform, or Xcode-related tasks, read the relevant Apple or Swift documentation first before proposing or making changes.
-- Prefer the simplest correct Swift that is easiest to read, reason about, and maintain.
-- Prefer explicit, consistent, and unambiguous names.
-- Prefer synthesized conformances and memberwise initialization whenever they satisfy the real need.
-- Avoid ceremony, wrappers, or extra abstraction layers unless they solve a concrete package problem.
-- Keep operator-facing errors, warnings, and log strings descriptive and human-readable.
+### Setup
 
-## Types and Architecture
+Use Swift 6.3 or newer on macOS 15 or newer. SwiftASB discovers the local Codex CLI from `PATH`, common Homebrew locations, or the npm global prefix.
 
-- Prefer value types for domain modeling.
-- Prefer concrete types internally and reserve protocols for real seams.
-- Mark classes `final` by default when reference semantics are required.
-- Keep dependency flow unidirectional and ownership obvious.
-- Treat this package as a library first: public API should be deliberate, documented, and tested.
+```bash
+swift package resolve
+```
+
+### Validation
+
+Run the package checks before committing package changes:
+
+```bash
+swift build
+swift test
+```
+
+Run the repo-maintenance validation before release or maintainer-surface changes:
+
+```bash
+bash scripts/repo-maintenance/validate-all.sh
+```
+
+Check whitespace before staging:
+
+```bash
+git diff --check
+```
+
+### Optional Project Commands
+
+Refresh generated Codex wire types through the maintainer entrypoint:
+
+```bash
+scripts/generate-wire-types.sh
+```
+
+Run the repo-maintenance shared sync entrypoint:
+
+```bash
+bash scripts/repo-maintenance/sync-shared.sh
+```
+
+Start a standard release from a feature branch with a clean committed worktree:
+
+```bash
+bash scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z
+```
+
+Validate DocC through Xcode when documentation changes:
+
+```bash
+xcodebuild docbuild -scheme SwiftASB -destination generic/platform=macOS -derivedDataPath tmp/xcode-docc/DerivedData
+```
+
+## Review and Delivery
+
+### Review Expectations
+
+- Keep package, docs, tests, and generated-wire surfaces aligned in the same branch when one change affects more than one of them.
+- Do not promote generated schema additions to public API just because they exist upstream; classify them as public now, observable-only for now, or internal-only before exposing them.
+- Keep README product-facing. Keep contributor workflow, local validation, live test flags, schema generation, DocC build commands, and release-prep details in `CONTRIBUTING.md` unless the README user needs them to consume the package.
+- PRs should identify the changed surface, explain any public API or docs boundary decision, and list the validation commands that ran.
+
+### Definition of Done
+
+- `swift build` and `swift test` pass for package changes unless the task is explicitly docs-only and no package behavior changed.
+- `bash scripts/repo-maintenance/validate-all.sh` passes for maintainer guidance, repo tooling, CI wrapper, or release setup changes.
+- Documentation reflects the actual shipped behavior, not aspirational API.
+- Live Codex runtime probes are described as observational when runtime behavior is nondeterministic.
+
+## Safety Boundaries
+
+### Never Do
+
+- Do not hand-edit `Package.resolved`.
+- Do not hand-edit the promoted generated wire snapshot in `Sources/SwiftASB/Generated/CodexWire/Latest/`; use `scripts/generate-wire-types.sh`.
+- Do not reintroduce a promoted generated v1 batch unless Gale explicitly asks for that compatibility surface again.
+- Do not commit dumped local schema artifacts under `codex-schemas/` unless Gale explicitly asks to commit them.
+- Do not commit temporary derived schemas or raw or patched quicktype staging output under `tmp/`.
+- Do not treat the generated wire layer as public Swift API.
+- Do not use `xcodebuild` as the default package validation path when plain SwiftPM validation is enough.
+
+### Ask Before
+
+- Ask before changing the public API ownership model, release boundary, licensing terms, or Codex CLI compatibility window.
+- Ask before adding dependencies that are not first-party or top-tier Swift ecosystem packages.
+- Ask before changing the shape of promoted generated-wire output.
+- Ask before committing local schema dumps or temporary generated artifacts that are normally untracked.
+
+## Local Overrides
+
+- No nested `AGENTS.md` files are currently present below the repository root.
+- If a more specific `AGENTS.md` is added later, follow the closer file for its subtree while keeping this root guidance as the package-wide baseline.
 
 ## Codex App-Server Wire Workflow
 
@@ -52,10 +166,3 @@
 - Keep `CodexWireInitializeResponse` hand-owned in its own dedicated Swift file next to the promoted generated v2 snapshot until the upstream v2 schema exposes that type directly.
 - Do not reintroduce a promoted generated v1 batch unless Gale explicitly asks for that compatibility surface again.
 - Treat the generated wire layer as an internal scaffolding surface, not the final public Swift API.
-
-## Testing and Tooling
-
-- Use Swift Testing as the default test framework.
-- Avoid XCTest unless an external constraint requires it.
-- Use `swift build` and `swift test` as the default first-pass validation commands.
-- Use `xcodebuild` only when Apple-platform integration details need validation beyond plain SwiftPM.

CONTRIBUTING.md

@@ -72,13 +72,19 @@ SwiftASB does not ship UI, but its observable companions are intended for SwiftU
 
 ### Verification
 
-Run the package checks before committing:
+Run the package checks before committing package changes:
 
 ```bash
 swift build
 swift test
 ```
 
+Run the repo-maintenance validation before release, CI wrapper, maintainer guidance, or tooling changes:
+
+```bash
+bash scripts/repo-maintenance/validate-all.sh
+```
+
 Validate DocC through Xcode when documentation changes:
 
 ```bash
@@ -109,6 +115,22 @@ Check whitespace before staging:
 git diff --check
 ```
 
+### Maintainer Scripts
+
+SwiftASB uses `scripts/repo-maintenance/` as the local-first maintainer surface. GitHub Actions stays a thin wrapper around these scripts, and branch protection should require the `validate` check context from `.github/workflows/validate-repo-maintenance.yml`.
+
+Use the shared sync entrypoint for future managed repo-maintenance refreshes:
+
+```bash
+bash scripts/repo-maintenance/sync-shared.sh
+```
+
+Use the release entrypoint from a feature branch or isolated worktree with a clean committed worktree:
+
+```bash
+bash scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z
+```
+
 ## Pull Request Expectations
 
 PRs should identify the changed surface, explain any public API or docs boundary decision, and list the validation commands that ran. Use the `documentation` label for docs-only work and a more specific label when the code surface is the stronger signal.

README.md

@@ -203,6 +203,8 @@ Contributor validation commands, live test flags, and the Xcode DocC build comma
 
 ```text
 .
+├── .github/
+│   └── workflows/
 ├── .spi.yml
 ├── CONTRIBUTING.md
 ├── Package.swift
@@ -222,6 +224,8 @@ Contributor validation commands, live test flags, and the Xcode DocC build comma
 │       ├── Public/
 │       └── Transport/
 └── scripts/
+    ├── generate-wire-types.sh
+    └── repo-maintenance/
 ```
 
 ## Release Notes

scripts/repo-maintenance/config/profile.env

@@ -0,0 +1,3 @@
+# Managed by maintain-project-repo. Do not hand-edit unless you also control the installer contract.
+REPO_MAINTENANCE_PROFILE="swift-package"
+REPO_MAINTENANCE_PROFILE_DESCRIPTION="Swift Package Manager repo-maintenance profile for library, tool, and package repos."