From 0692ce559bb85f9e57302ef00f38d868037c98c7 Mon Sep 17 00:00:00 2001 From: Maoxin1 <122297182+Maoxin1@users.noreply.github.com> Date: Sat, 29 Aug 2026 23:43:37 +0800 Subject: [PATCH 1/2] chore: improve compatibility and release readiness --- CHANGELOG.md | 2 ++ COMPATIBILITY.md | 28 ++++++++++++++++++++++++++++ README.md | 10 ++++++++++ RELEASING.md | 15 +++++++++++++++ install.ps1 | 7 ++++++- tests/validate_install.ps1 | 11 +++++++++++ 6 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 COMPATIBILITY.md create mode 100644 RELEASING.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4898caa..65229cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and - Standalone documentation and static contract tests for `_factbot` and `_mantou`. - Repository-wide validation for local Markdown links, structured data, and common privacy leaks. - Contribution, security, issue, pull-request, and dependency-update configuration. +- Runtime and model compatibility guidance plus a maintainer release checklist. +- Installer `-WhatIf` support for previewing forced updates without changing files. ### Changed diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..590fcbc --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,28 @@ +# Compatibility + +This package contains Codex custom-agent configuration and supporting files. Local validation confirms repository structure and syntax; model availability and product features still depend on the user's Codex workspace. + +## Runtime requirements + +- Codex must support custom agents with `model`, `model_reasoning_effort`, and `sandbox_mode` configuration fields. +- `_factbot` and `_manuel` request `gpt-5.6-terra`; `_invest` and `_mantou` request `gpt-5.6-sol`. Installation does not grant access to either model. +- PowerShell is required for installation and the repository validation entry points. +- Python 3.11 or later is required for static validators and unit tests. +- `_mantou` requires a Windows interactive session with `Set-Clipboard` and `Get-Clipboard` available. +- `_invest` can optionally route approved writes to Obsidian. Its local vault path is supplied outside the public package. + +## Portability + +If a configured model is unavailable, choose an accessible model with equivalent tool and reasoning support, update the relevant TOML file, and run `./tests/validate_repository.ps1` before installation. Treat that change as a local compatibility override unless the repository's supported defaults are intentionally being changed. + +The default CI exercises Windows with Python 3.11 and 3.13. It does not call paid model services or perform live behavioral evaluation. + +## Upgrade check + +Before upgrading Codex or this package: + +1. run `./install.ps1 -Force -WhatIf` to preview managed targets; +2. review the changelog and agent-specific behavior changes; +3. run `./tests/validate_repository.ps1`; +4. install with `-Force`, then restart Codex; +5. exercise each agent with a non-sensitive smoke test before relying on it for substantive work. diff --git a/README.md b/README.md index 3903b7e..2c8dc76 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,12 @@ The installer copies the agent configuration files and support libraries to `$en ./install.ps1 -Force ``` +Preview a forced update without changing the target directory: + +```powershell +./install.ps1 -Force -WhatIf +``` + `-Force` updates only files managed by this package at their existing relative paths. It does not remove unmanaged local files such as `agents/_invest/knowledge-map.local.md`. @@ -50,6 +56,8 @@ Maintainers can run the complete local validation suite with Restart Codex after installation so the custom-agent list is reloaded. +Before installation, review [`COMPATIBILITY.md`](COMPATIBILITY.md) for model access, platform, and runtime requirements. The package validates configuration syntax locally, but it cannot grant access to a model that is unavailable in the user's Codex workspace. + ## Usage Ask Codex to call the relevant agent: @@ -68,6 +76,8 @@ See [`agents/_manuel/README.md`](agents/_manuel/README.md) and [`agents/_invest/ - [`CONTRIBUTING.md`](CONTRIBUTING.md): validation, change, and release policy. - [`SECURITY.md`](SECURITY.md): private security and privacy reporting. - [`CHANGELOG.md`](CHANGELOG.md): repository-wide change history. +- [`COMPATIBILITY.md`](COMPATIBILITY.md): supported runtime assumptions and portability notes. +- [`RELEASING.md`](RELEASING.md): maintainer release checklist. - [`AGENTS.md`](AGENTS.md): constraints for automated repository maintenance. ## Source and copyright note diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..e9690d6 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,15 @@ +# Releasing + +Releases use Semantic Versioning and copy their user-visible notes from `CHANGELOG.md`. + +## Checklist + +1. Confirm the intended version and move relevant entries from `Unreleased` to a dated version section. +2. Review model identifiers and the assumptions in `COMPATIBILITY.md` against current official Codex documentation. +3. Run `./tests/validate_repository.ps1` from a clean checkout. +4. Confirm the `Validate` workflow succeeds on the exact release commit. +5. Create a signed or annotated `vMAJOR.MINOR.PATCH` tag. +6. Create the GitHub Release from that tag, copy the changelog notes, and include any migration steps. +7. Test a clean installation from the released archive without using private overlays or credentials. + +Do not publish a release while required validation is skipped, a model identifier is known to be unavailable to the intended audience, or private material appears in the diff or archive. diff --git a/install.ps1 b/install.ps1 index a811010..be2ea25 100644 --- a/install.ps1 +++ b/install.ps1 @@ -1,4 +1,4 @@ -[CmdletBinding()] +[CmdletBinding(SupportsShouldProcess)] param( [switch]$Force ) @@ -33,6 +33,11 @@ foreach ($item in $items) { } } +if (-not $PSCmdlet.ShouldProcess($targetRoot, "Install managed Codex agent files")) { + Write-Host "No files changed. Target would be $targetRoot" + return +} + New-Item -ItemType Directory -Path $targetRoot -Force | Out-Null # Copy managed files to their exact relative paths. Copying a directory onto an diff --git a/tests/validate_install.ps1 b/tests/validate_install.ps1 index 9fa23b0..8a6cb6a 100644 --- a/tests/validate_install.ps1 +++ b/tests/validate_install.ps1 @@ -48,6 +48,16 @@ try { Assert-True (-not (Test-Path -LiteralPath (Join-Path $cleanRoot 'agents/_invest/_invest'))) 'Force update created nested _invest/_invest.' Assert-True (-not (Test-Path -LiteralPath (Join-Path $cleanRoot 'agents/_manuel/_manuel'))) 'Force update created nested _manuel/_manuel.' + $managedTarget = Join-Path $cleanRoot 'agents/_mantou.toml' + Set-Content -LiteralPath $managedTarget -Value 'local-managed-change' -Encoding utf8 + $beforeWhatIf = (Get-FileHash -LiteralPath $managedTarget -Algorithm SHA256).Hash + & $installer -Force -WhatIf + $afterWhatIf = (Get-FileHash -LiteralPath $managedTarget -Algorithm SHA256).Hash + Assert-True ($beforeWhatIf -eq $afterWhatIf) '-WhatIf changed a managed target file.' + & $installer -Force + Assert-ManagedFilesMatch $cleanRoot + Assert-True ((Get-Content -Raw -LiteralPath $overlay).Trim() -eq 'private-local-overlay') 'Update after -WhatIf changed the private overlay.' + $partialRoot = Join-Path $testRoot 'partial' $partialInvest = Join-Path $partialRoot 'agents/_invest' New-Item -ItemType Directory -Path $partialInvest -Force | Out-Null @@ -67,6 +77,7 @@ try { Write-Host 'INSTALL VALIDATION PASSED' Write-Host '- clean installation matches all packaged files' Write-Host '- forced update is idempotent and preserves private overlays' + Write-Host '- WhatIf previews a forced update without changing managed files' Write-Host '- collision preflight performs no partial installation' } finally { From 9152c17576310a6c0e5c129dd15433bcbdfadaae Mon Sep 17 00:00:00 2001 From: Maoxin1 <122297182+Maoxin1@users.noreply.github.com> Date: Sun, 30 Aug 2026 08:44:14 +0800 Subject: [PATCH 2/2] docs: prepare changelog for v0.1.0 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65229cb..2610a6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and ## [Unreleased] +## [0.1.0] - 2026-08-30 + ### Added - Windows CI for installer, agent validators, unit tests, PowerShell parsing, and TOML parsing.