Add package-owned progression logging

AGENTS.md

@@ -15,6 +15,7 @@ Read only the guides relevant to the task:
 - [SwiftLint](AgentGuidelines/Guidelines/Swift/SwiftLint.md)
 - [Unit and integration testing](AgentGuidelines/Guidelines/Testing/UnitTesting.md)
 - [Documentation](AgentGuidelines/Guidelines/Documentation.md)
+- [Logging](AgentGuidelines/Guidelines/Logging.md)
 - [Packages](AgentGuidelines/Guidelines/Packages.md)
 - [CI/CD](AgentGuidelines/Guidelines/CICD.md)
 - [Git repositories and SSH-first cloning](AgentGuidelines/Guidelines/Git/Repositories.md)
@@ -39,3 +40,4 @@ Redux, SwiftUI, and application-localization guidance do not apply to the packag
 - Host applications own mapping from their domain identifiers and outcomes into `PKEvent`.
 - Preserve compiler-synthesized value semantics and serialization when evolving public models.
 - Update tests, DocC, README examples, and release notes when public behavior changes.
+- Use logging subsystem `com.thatfactory.progressionkit`, category `progression`, and canonical package emoji `📈`.

AgentGuidelines/AGENTS.md

@@ -10,6 +10,7 @@ This public repository is the versioned source of truth for reusable ThatFactory
 - Distill durable policy from Xcode-provided skills; do not copy exported Apple skills into this repository.
 - Do not include private company information, credentials, personal absolute paths, or consumer-specific implementation details.
 - When shared and consumer guidance differ, the consumer's nearest applicable `AGENTS.md` is the explicit specialization.
+- Before changing this repository, verify that the consumer's checked-in guidelines version is current where applicable.
 
 ## Documentation changes
 
@@ -19,6 +20,21 @@ This public repository is the versioned source of truth for reusable ThatFactory
 - Use relative Markdown links inside this repository.
 - Update `README.md` when adding, moving, or removing a guide.
 - Update `CHANGELOG.md` and `VERSION` for a release.
+- When releasing a new version, update the version in both the README installation command and the README consumer-update command. Keep both commands aligned with the new release, for example:
+
+  ```sh
+  git subtree add \
+    --prefix=AgentGuidelines \
+    https://github.com/thatfactory/agent-guidelines.git \
+    <version> \
+    --squash
+
+  git subtree pull \
+    --prefix=AgentGuidelines \
+    https://github.com/thatfactory/agent-guidelines.git \
+    <version> \
+    --squash
+  ```
 
 ## Validation
 

AgentGuidelines/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.0.7] - 2026-07-23
+
+### Added
+
+- Shared logging ownership, subsystem, package emoji, message design, privacy, testing, and filtering guidance.
+- Logging pointers for application development, Swift packages, and consumer instruction templates.
+
+## [0.0.6] - 2026-07-22
+
+### Added
+
+- Generic Redux store contracts, state/action, service-boundary, projection, and middleware guidance.
+- Generic GitHub Actions workflow, self-hosted runner, build strategy, and failure-investigation guidance.
+- Shared documentation conventions and test-tag/mock guidance.
+
+## [0.0.5] - 2026-07-21
+
+### Added
+
+- Default DocC documentation and GitHub Pages publishing guidance for Swift packages.
+
+## [0.0.4] - 2026-07-21
+
+### Added
+
+- Development guidance for reusability-first design and checking the latest shared-guidelines version before project work.
+
+### Changed
+
+- Require an approved pull request before releasing `agent-guidelines` or any consumer package.
+
 ## [0.0.3] - 2026-07-21
 
 ### Added

AgentGuidelines/Guidelines/Architecture/Redux.md

@@ -39,6 +39,28 @@ Use this guide for applications that explicitly adopt the ThatFactory Redux arch
 
 The store reduces the original action first, then awaits middleware and sequentially dispatches returned follow-up actions. Keep ordering observable and deterministic. Do not start unstructured work inside reducers or hide state changes inside services.
 
+## Store
+
+Use one observable store as the source of truth and inject it at the application root. A store implementation may expose aliases like these:
+
+```swift
+typealias AppStore = Store<AppState, AppAction>
+typealias StateType = Equatable & Codable
+typealias ActionType = Equatable
+typealias Reducer<State: StateType, Action: ActionType> = (State, Action) -> State
+typealias Middleware<State: StateType, Action: ActionType> = (State, Action) async -> Action?
+```
+
+Dispatch is asynchronous and ordered:
+
+1. Reduce the original action.
+2. Capture the resulting state.
+3. Await each registered middleware with that state and action.
+4. Collect returned actions.
+5. Dispatch follow-up actions sequentially.
+
+Use only `await store.dispatch(_:)`. Do not add a fire-and-forget dispatch API.
+
 ## Canonical physical folders
 
 These are filesystem folders, not Xcode groups. New single-application repositories use this structure by default:
@@ -118,6 +140,8 @@ Put the root state and domain sub-states in `Redux/State/`. Prefer focused value
 
 State stores durable facts. Avoid storing values that are cheap, deterministic derivations unless caching is an explicit measured requirement.
 
+Sub-states should conform to `Equatable` and `Codable`; add `Sendable` when their values and concurrency boundaries require it. Keep root state and root actions for genuine cross-domain behavior. Keep domain action cases descriptive of intent or outcomes and route them through the root action.
+
 ### Reducer
 
 Put reducer functions in `Redux/Reducer/`. A reducer receives state and an action and returns new state. It must not:
@@ -135,7 +159,7 @@ Use the smallest state and action inputs that correctly express the transition.
 
 Put middleware in `Redux/Middleware/`. Middleware may call injected services and return a follow-up action. It must not mutate store state directly.
 
-Inject services, clocks, identifier generators, and providers through parameters so middleware tests remain deterministic. Register middleware in one root composition file such as `AppMiddlewares.swift`.
+Inject services, providers, managers, clocks, and identifier generators through parameters so middleware tests remain deterministic. Register middleware in one root composition file such as `AppMiddlewares.swift`. Reducers own every state mutation.
 
 Create a feature subfolder when a domain has multiple middleware files:
 
@@ -158,6 +182,8 @@ Put focused external-boundary abstractions in `Services/<Capability>/`. Services
 
 Prefer a protocol or otherwise injectable contract when a service must be replaced in tests. Keep transport-specific details behind the service boundary.
 
+Views dispatch actions; middleware calls services. Views never call a service directly for Redux-owned behavior.
+
 ### Tools
 
 Put genuinely cross-cutting implementation utilities in `Tools/`. This is not a miscellaneous folder. Feature-only formatters, helpers, constants, or factories stay beside that feature. Promote them to `Tools/` only after they have a clear cross-feature role.
@@ -177,6 +203,8 @@ View/Account/
 
 If a projection exists only to render one screen, it is view-layer code even when its input is `AppState`.
 
+Projection tests mirror the production view path under the test target.
+
 ### Resources
 
 Put catalogs, assets, preview assets, configuration resources, and test plans in `Resources/` or the concrete resource folders declared locally. Production targets must not depend on test fixtures.

AgentGuidelines/Guidelines/CICD.md

@@ -12,7 +12,15 @@
 - Do not place secrets in workflow files, logs, fixtures, or command arguments that may be echoed.
 - Keep release workflows separate from pull-request validation when their permissions differ.
 
-## Pull-request CI
+## `ci-pr.yml`
+
+Projects using GitHub Actions should keep pull-request validation in `.github/workflows/ci-pr.yml`, triggered by `pull_request` events for `opened`, `synchronize`, and `reopened`.
+
+Use GitHub-hosted runners for jobs that can run on the hosted operating system and toolchain. When a job uses a self-hosted runner, document and select it through the repository's `Runner labels:` rather than hard-coding a machine name in shared guidance.
+
+### Runner labels:
+
+When a workflow uses self-hosted runners, document the labels required by each job in this section of the consumer's CI/CD guide. Always include `self-hosted` and add only stable capability or environment labels needed to select the runner, such as an operating system, architecture, toolchain, or signing capability. Keep machine names and changing fleet details out of shared guidance.
 
 A typical Swift package validates:
 
@@ -24,14 +32,27 @@ A typical Swift package validates:
 
 An Xcode application validates its declared scheme and test plan. Use the same project/workspace, configuration, and platform assumptions documented for local development.
 
-## Investigation
+Xcode projects and Swift packages must run on self-hosted macOS runners with the required Xcode, Swift toolchains, simulators, certificates, and signing environment. Do not use `macos-latest` for those jobs. For Xcode projects, test with `xcodebuild test` and explicit simulators, then validate compilation with `xcodebuild build CODE_SIGNING_ALLOWED=NO` across the supported platforms. For Swift packages, use Swift Package Manager commands such as `swift test` and `swift build`; packages do not require simulator selection, but may require the self-hosted signing environment for packaging or collection workflows. Generic jobs that do not require Apple tooling may use GitHub-hosted Linux or other suitable runners. CI validates tests and compile health, not app-store distribution.
+
+## `ci.yml`
+
+Validation of merges to `main` should live in `.github/workflows/ci.yml`, triggered by `push` on `main`. Use the same build, test, lint, and platform coverage as pull-request validation unless the repository documents a deliberate difference.
+
+## Failure investigation
+
+1. Use GitHub MCP connector tools to inspect check runs and logs for the failing commit or pull request.
+2. Use `gh` for fast local triage when needed.
+3. Reproduce locally with the exact build or test command shown in the failing job logs.
+
+Useful commands:
+
+```bash
+gh run list --limit 10
+gh run view <run-id>
+gh run view <run-id> --log
+```
 
-1. Identify the first meaningful failing step rather than treating later cancellations as independent failures.
-2. Reproduce locally with the closest supported toolchain when practical.
-3. Separate infrastructure or dependency-resolution failures from code failures.
-4. Fix the root cause in the narrowest appropriate layer.
-5. Re-run the affected local validation before relying on remote CI.
-6. Update durable CI documentation when the workflow or investigation process changes.
+Distinguish compiler errors from lint violations, test failures from simulator or runtime infrastructure failures, and single-job failures from cross-platform matrix failures. Identify the first meaningful failing step, fix the narrowest root cause, and re-run affected validation.
 
 ## Releases
 

AgentGuidelines/Guidelines/Development.md

@@ -0,0 +1,13 @@
+# Development
+
+## Reusability first
+
+When developing a new feature or responding to a feature request, consider shared code first. If the code fits an existing package, suggest extending that package instead of adding the implementation directly to an application. Also consider whether the change belongs in a new Swift package, even when that package does not exist yet. Prefer reusable, focused package APIs when they can serve more than one consumer.
+
+## Guidelines version
+
+Before changing a project, verify that it uses the latest released version of `agent-guidelines`. Check the project's `AgentGuidelines/VERSION` against the latest release, update the subtree or equivalent when it is behind, and read the updated applicable guides before starting implementation. This check is manual and must be performed at the beginning of each project task.
+
+## Logging
+
+Applications own their orchestration, lifecycle, and product-domain diagnostics. Follow the shared [logging guide](Logging.md) and rely on each dependency to log its own implementation. Do not duplicate or reformat package-internal operations in the application log.

AgentGuidelines/Guidelines/Documentation.md

@@ -1,5 +1,9 @@
 # Documentation
 
+- Use PascalCase Markdown filenames without spaces.
+- Keep the folder flat until one topic genuinely requires several files.
+- Prefer current implementation over speculative future design; label known gaps explicitly.
+
 ## Code-level documentation
 
 - Document structs, classes, enums, protocols, actors, and other significant types with focused `///` DocC comments.

AgentGuidelines/Guidelines/Git/Repositories.md

@@ -20,3 +20,23 @@ git clone git@github.com:<owner>/<repository>.git
   ```
 
 HTTPS remains appropriate for deliberately read-only retrieval, ephemeral automation, or environments where SSH credentials are unavailable. A public Git subtree remote may also remain HTTPS because consumers fetch tagged content without pushing to the guideline repository.
+
+## GitHub CLI authentication recovery
+
+Treat a reported invalid `GITHUB_TOKEN` as potentially transient or environment-specific. Do not abandon the `gh` CLI or switch protocols solely because one Codex shell reports that token as invalid.
+
+When `gh` authentication appears inconsistent:
+
+1. Retry `gh auth status` in a fresh shell.
+2. If the user can run commands locally, ask them to confirm `gh auth status` and share only the redacted result; never request or print the token itself.
+3. Retry the original `gh` command after authentication is confirmed. Preserve the CLI workflow for repository inspection, Actions logs, and pull-request operations.
+4. If an injected environment variable is shadowing the stored GitHub CLI credential, compare the credential-backed check without exposing secrets:
+
+   ```sh
+   env -u GITHUB_TOKEN gh auth status
+   ```
+
+   If that succeeds, use the authenticated CLI session for the task or refresh it with `gh auth refresh` as appropriate. Do not copy a token into shell history, command arguments, files, or chat.
+5. Use SSH for Git transport only when the CLI remains unavailable after retry and the operation is specifically a Git fetch, commit, or push. Continue using `gh` for GitHub API operations whenever it is working.
+
+An environment mismatch is not evidence that the user's GitHub account or token is invalid. Record the failed command and exact non-secret error, retry after the authentication check, and report the blocker only after repeated attempts fail.

AgentGuidelines/Guidelines/GitHub/PullRequests.md

@@ -20,7 +20,10 @@ Opening a pull request starts review; it does not authorize merging it.
 5. If feedback should not be implemented, reply in the original thread with a concise technical reason.
 6. Reply to implemented feedback with what changed and where.
 7. Resolve a thread only after its concern has been addressed or explicitly declined.
-8. Recheck the pull request immediately before merge for late comments and check-state changes.
+8. After addressing review comments, update the pull-request description so it matches the current implementation, validation, and any remaining limitations.
+9. Recheck the pull request immediately before merge for late comments and check-state changes.
+
+When replying with a commit reference, write the commit hash as raw text without backticks (for example, the hash 185c04f should remain 185c04f). GitHub then auto-links the hash to the commit.
 
 A thumbs-up or clean Codex review satisfies the agent-review step, but it does not replace any human approval required by the repository. Do not enable auto-merge before all review gates are satisfied.