KbWen · KbWen · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026
@@ -26,7 +26,7 @@ TARGET="${TARGET:-.}"
 TARGET="${TARGET%/}"
 
 MANIFEST_FILE="$TARGET/.agentcortex-manifest"
-ACX_VERSION="1.8.26"
+ACX_VERSION="1.8.27"
 
 # --- Self-deploy guard ---
 TARGET_ABS="$(cd "$TARGET" 2>/dev/null && pwd || echo "$TARGET")"

@@ -1,7 +1,7 @@
 {
-  "expected_sha": "e911bdf70de6a546bb4ebe8ec81deb6635686b0b48b1a05530879c5d9b8ae458",
+  "expected_sha": "e2c9006167cbf4c4768d530ba9b7cfe647086093be1c6fcb4358c89ca7e054c6",
   "mode": "replace",
-  "new_sha": "e2c9006167cbf4c4768d530ba9b7cfe647086093be1c6fcb4358c89ca7e054c6",
+  "new_sha": "e0fb3d84bdbf1d4dd8a3f0f3f27a62ac3f4b57b8e482e5033000ec4d1f553dda",
   "target": ".agentcortex/context/current_state.md",
-  "timestamp": 1789359115
+  "timestamp": 1789364931
 }
@@ -178,3 +178,4 @@
 {"archive_file": ".agentcortex/context/archive/global-lessons-archive.md", "archived_at": "2026-09-10", "archived_body_sha": "7d331603", "archived_prev": "GENESIS", "prev_sha": "13dc602a", "successor_body_sha": "4faa557a", "successor_new_prev": "GENESIS", "type": "lesson_archive"}
 {"branch": "docs/retro-skill-description-lessons", "classification": "quick-win", "decisions": ["D-1: archive [classification-flow] to free a Global Lessons slot (user choice)", "D-2: add one lesson, not four"], "log": "docs-retro-skill-description-lessons-20260910.md", "modules": [".agentcortex/context/current_state.md", ".agent/rules/repo-gotchas.md", ".agentcortex/context/archive/ship-history-2026.md"], "patterns": ["retro", "memory-to-repo-records", "ship-history-rotation"], "prev_sha": "e9446cc6", "shipped": "2026-09-10", "specs": []}
 {"branch": "fix/downstream-ignore-python-bytecode", "classification": "quick-win", "decisions": ["D-1: framework-scoped .agentcortex/**/__pycache__/ instead of repo-wide __pycache__/ + *.pyc", "D-2: new ignore-block entries go last; no marker-bounded strip"], "log": "fix-downstream-ignore-python-bytecode-20260914.md", "modules": [".agentcortex/bin/deploy.sh", "tests/ci/test_deploy_tiering.py"], "patterns": ["contributor-pr-takeover", "downstream-gitignore", "redeploy-idempotency"], "prev_sha": "cecfa10e", "shipped": "2026-09-14", "specs": []}
+{"branch": "chore/release-v1.8.27", "classification": "quick-win", "decisions": [], "log": "chore-release-v1.8.27-20260914.md", "modules": ["release metadata", "CHANGELOG.md"], "patterns": ["release-cut"], "prev_sha": "b812152b", "shipped": "2026-09-14", "specs": []}
@@ -0,0 +1,160 @@
+# Work Log: chore/release-v1.8.27
+
+## Header
+
+- Branch: `chore/release-v1.8.27`
+- Classification: `quick-win`
+- Classified by: `claude-opus-5`
+- Frozen: `2026-09-14`
+- Created Date: `2026-09-14`
+- Owner: `KbWen`
+- Guardrails Mode: `Quick`
+- Current Phase: `ship`
+- Diff Base SHA: `7bc4955`
+- Checkpoint SHA: `7bc4955`
+- Recommended Skills: `none`
+- Primary Domain Snapshot: `release metadata`
+- SSoT Sequence: `171`
+
+---
+
+## Session Info
+
+- Agent: `claude-opus-5`
+- Session: `2026-09-14T05:46:46Z`
+- Platform: `claude-code`
+
+---
+
+## Task Description
+
+Cut release v1.8.27 on the owner's request after PR #435 merged. Bump the seven canonical version surfaces plus `CITATION.cff` `date-released`, and write the CHANGELOG entry for the four units merged since v1.8.26 (#425, #436, #437/#438, #435). No engine, gate, or configuration change.
+
+---
+
+## Phase Sequence
+
+| Phase | Status | Entered | Notes |
+|---|---|---|---|
+| bootstrap | done | 2026-09-14 | quick-win on the `chore/release-v1.8.26` precedent; branch from `origin/main` `7bc4955`, upstream tracking removed so a bare push cannot target main |
+| plan | done | 2026-09-14 | 8 surfaces + CHANGELOG; adopter delta measured before writing notes |
+| implement | done | 2026-09-14 | asserted single-occurrence bumps; CHANGELOG entry |
+| review | n/a | - | quick-win: optional; notes checked against each unit's Ship History record |
+| test | done | 2026-09-14 | release consistency guard + validators locally; full suite on PR CI |
+| handoff | n/a | - | quick-win exempt |
+| ship | done | 2026-09-14 | SSoT Ship History (rotated) + heartbeat 172, log archived, INDEX chained |
+
+---
+
+## Phase Summary
+
+- bootstrap/plan: `git diff --name-only v1.8.26..7bc4955` gives 26 files; intersected with `deploy_manifest_golden.txt`, 6 reach an adopter: `deploy.sh`, `repo-gotchas.md`, `trigger-compact-index.json` (core), the `production-readiness` and `systematic-debugging` `SKILL.md` (scaffold), `current_state.md` (scaffold, adopter copy preserved). `security.yml`, `docs/INSTALL.md`, tests and records are upstream-only.
+- implement: 7 surfaces + `date-released` bumped by `scratchpad/bump_version.py` (each replace asserts exactly 1 occurrence; zh-TW files re-decoded as UTF-8 after write). CHANGELOG leads with the one action an adopter may need (`git rm -r --cached .agentcortex/tools/__pycache__`), because the ignore rule does not untrack already-committed bytecode and deploy runs no git commands. The #437 bullet says no trigger-rate change was measured, matching that unit's own carried limitation.
+- ship: see Final Verification. Post-merge steps are NOT done at merge: lightweight tag `v1.8.27` + `gh release create --latest` (repo-gotchas §12).
+
+⚡ ACX
+
+---
+
+## Gate Evidence
+
+- Gate: bootstrap | Verdict: PASS | Classification: quick-win | Timestamp: 2026-09-14T05:46:46Z
+- Gate: plan | Verdict: PASS | Classification: quick-win | Timestamp: 2026-09-14T05:47:00Z
+- Gate: implement | Verdict: PASS | Classification: quick-win | Timestamp: 2026-09-14T05:47:44Z
+- Gate: test | Verdict: PASS | Classification: quick-win | Timestamp: 2026-09-14T05:48:00Z
+- Gate: ship | Verdict: PASS | Classification: quick-win | Timestamp: 2026-09-14T05:48:51Z
+
+---
+
+## External References
+
+| Type | Path / URL | Notes |
+|---|---|---|
+| PR | https://github.com/KbWen/agentic-os/pull/435 | the downstream fix this release carries |
+| Guard | `tests/ci/test_release_version_consistency.py` | pins all 8 surfaces to `deploy.sh` |
+
+---
+
+## Known Risk
+
+- Bytecode already committed by an adopter stays tracked; only the release notes carry the one-line cleanup.
+- Release is incomplete at merge: tag + GitHub Release are manual (forgotten twice before). Recorded here and in the PR body before merging.
+- Rollback: revert the release commit; delete the tag and Release if already published.
+
+---
+
+## Decisions
+
+none
+
+---
+
+## Conflict Resolution
+
+none
+
+---
+
+## Skill Notes
+
+none
+
+---
+
+## Drift Log
+
+- SSoT write script aborted on its own sequence assertion before any write (a `sed` edit to the copied script had not applied); corrected by hand and re-run. `git status` showed `current_state.md` unmodified between the two runs.
+- Ship History rotated at cap 10: `Ship-main-2026-08-27` -> `archive/ship-history-2026.md`, guarded half first.
+
+---
+
+## Review Feedback
+
+none
+
+---
+
+## Red Team Findings
+
+none
+
+---
+
+## Design Reference
+
+none
+
+---
+
+## Observability
+
+none
+
+---
+
+## Resume
+
+none
+
+---
+
+## Test Gate Results
+
+- `pytest tests/ci/test_release_version_consistency.py` -> 2 passed, exit 0 (after the bump and CHANGELOG insert).
+- Whole suite: not re-run locally for a version-string cut; it runs on the PR's CI (Linux + 3 Windows shards) before merge. The code it would exercise is unchanged since PR #435's local full run and green CI.
+
+---
+
+## Evidence
+
+- Stale-version sweep after bump: `git grep 1.8.26` outside `CHANGELOG.md`, `archive/`, `current_state.md` and the backlog -> no hits.
+- zh-TW banner diffs byte-identical except the version digits (`cat -v` of both sides).
+
+## Final Verification
+
+> Sole location of this cut's closing figures, taken against `386d522` (tree clean) after every other write.
+
+- `validate.sh` exit 0 and `validate.ps1` exit 0: both `pass=99 warn=4 fail=0 skip=3`, identical; all 4 WARNs pre-existing
+- `test_release_version_consistency.py` 2 passed; `check_audit_chain.py` intact; `check_ssot_caps.py` ship history 10/10
+
+⚡ ACX
@@ -2,6 +2,10 @@
 
 Archived from `current_state.md ## Ship History` to stay within the 10-entry cap. Entries are rotated out verbatim (per ship.md §205 — never edited), newest-archived first.
 
+### Ship-main-2026-08-27
+- Feature shipped: **v1.8.25 closes the release-to-downstream consistency gap.** Backlog #182 adds a pytest guard that derives the canonical version from `deploy.sh`, pins every release surface plus citation-date ordering, and was proved red against the v1.8.24 runtime-guide drift before repair. Companion backlog #180 excludes `.claude` from bare pytest discovery, eliminating duplicate collection from leftover agent worktrees. The adversarial premortem and clean-downstream reproduction are preserved in `docs/reviews/2026-08-26-govern-audit-release-downstream-premortem.md`; implementation commit `6984551`.
+- Tests: Pass — release consistency + deploy-manifest snapshot 3 passed; bare collection 916 tests / 0 errors; final post-archive validators and CI-equivalent suite recorded in `.agentcortex/context/archive/main-20260827.md`.
+
 ### Ship-fix-ignore-assertion-binding-2026-08-24
 - Feature shipped: **the guard that protects the governance record stopped agreeing with `.gitignore` and started asking git.** A sibling fork reported six governance findings against the shared ancestor; diagnosis against this tree confirmed one root cause worth fixing here, at two altitudes. The validators' `.gitignore preserves persistent SSoT artifacts` check compared whole `.gitignore` lines against a fixed list of directory paths — so `.agentcortex/context/archive/*.md`, which hides the archived Work Logs without ever spelling that directory, sailed past it. Reproduced before fixing: one appended line left `validate.sh` at `fail=0` while `git check-ignore` confirmed the logs were hidden. **The same blind spot had grown independently in both forks of the same ancestor**, which is what makes it a class. The check now probes a representative FILE inside each protected artifact (a directory probe reproduces the original blindness, since `docs/specs/*.md` never matches the directory), tri-state so a check that could not run reports SKIP rather than assurance, and is no longer gated on `.gitignore` existing — that branch emitted `.gitignore absent -- no persistent SSoT artifacts are ignored`, a PASS asserted without looking at anything, while `.git/info/exclude` and a global excludes file hide files just as well.
 - **Two adopter-facing regressions were introduced and caught before ship, both by an independent reviewer rather than by self-review.** (1) `check-ignore -v` exits 0 whenever a pattern **matched**, negations included: on the ordinary `docs/adr/*` + `!docs/adr/*.md` idiom `-v` exits 0 while `-q` exits 1 and git tracks the file, so reading `-v`'s status as the verdict reds a correct adopter **and names their protective `!` line as the pattern to remove**. (2) `check-ignore` skips **tracked** paths without `--no-index`, so `current_state.md` — the one real path in the probe list — was inert in every healthy deploy: a detection *narrowing* shipped inside a change whose stated purpose was broadening. Both measured, both fixed, both mutation-guarded. A third, found by the scenario sweep: deployed under an outer repository's `vendor/`-style ignore every probe resolves ignored, and per-probe blame points at that outer rule — now diagnosed as its own cause with its own remedy, through the **same** emission site so the ADR-006 native ratchet stays at **204/204**.

@@ -12,9 +12,9 @@
   - Active Work Log Path: derive <worklog-key> from the raw branch name using filesystem-safe normalization before any gate checks.
   - Workflows & Policies: `.agent/workflows/*.md`, `.agent/rules/*.md`
 - **Project Name**: (set by /app-init)
-- **Last Updated**: 2026-09-14T04:11:55Z
+- **Last Updated**: 2026-09-14T05:48:51Z
 - **Last Verified**: 2026-09-09
-- **Update Sequence**: 171
+- **Update Sequence**: 172
 - **ADR Index**:
   - docs/adr/ADR-001-governance-friction-tuning.md — ADR-001: Governance Friction Tuning, accepted 2026-04-23 (amended 2026-07-16: `design_tool` capability-seam escape rejected — D2 reaffirmed, do NOT retry)
   - docs/adr/ADR-002-guarded-governance-writes.md — ADR-002: Guarded Governance Writes (lock unification + CI lint + lifecycle frontmatter), accepted 2026-04-25
@@ -113,6 +113,15 @@
 - [Category: skill-description-cost][Severity: HIGH][Trigger: editing-skill-md][prev: 3edf8155] Every character added to a .agents/skills/*/SKILL.md costs about 2.33 tokens against the aggregate lifecycle ceiling, roughly 8.9x its own size: analyze_token_lifecycle.py counts the whole file once per scenario the skill is a candidate for, plus first-load and continuation. Headroom was 431 before PR #437 and is 113 after it. On #437, rewriting two descriptions to the app-init.md:200 standard reached 355225 against the 355000 ceiling while the targeted tests, both validators and two review rounds all stayed green - only the full suite caught it. Before editing any SKILL.md, measure with analyze_token_lifecycle.py --root . --format json. The conflict between that description contract and this ceiling is open as backlog #199 and needs an owner decision before further skill-description work, including #198.
 ## Ship History
 
+### Ship-chore-release-v1.8.27-2026-09-14
+
+- Feature shipped: **v1.8.27** packages the four units merged since v1.8.26: the downstream bytecode-ignore fix (**PR #435**, #430, contributed by @zerone0x and completed in place), two skill descriptions that now lead with their activation conditions (#437) plus its retro records (#438), the TruffleHog scanner digest completion (#425), and the `custom-*` activation on-ramp row in `docs/INSTALL.md` (#436). The seven canonical version surfaces plus `CITATION.cff date-released` moved 1.8.26 -> 1.8.27 and 2026-09-05 -> 2026-09-14. Each was bumped by an asserted single-occurrence replace and is pinned by `test_release_version_consistency.py` (**2 passed**). **The cut itself changes no engine, gate order, deployed file set, or configuration.**
+- **The adopter delta was measured before the notes were written.** Of the 26 files changed since `v1.8.26`, **6** are in the deploy set:
+  - core: `deploy.sh`, `repo-gotchas.md`, `trigger-compact-index.json`
+  - scaffold: the `production-readiness` and `systematic-debugging` `SKILL.md`, and `current_state.md` (the adopter's own copy is preserved)
+- **The release notes lead with the one action an adopter may need:** `git rm -r --cached .agentcortex/tools/__pycache__`, for installs that already committed bytecode. A `.gitignore` rule does not untrack files, and deploy deliberately runs no git commands in an adopter's repository. The #437 bullet repeats that unit's carried limitation: no trigger-rate change was measured on any host.
+- Tests: release guard **2 passed** locally, and both validators are recorded in the archived Work Log §Final Verification. This is a subset: the whole suite runs on the release PR's CI (Linux + 3 Windows shards) before merge. PR #435's local 951-test run and its green CI cover the unchanged code. Post-merge completion per repo-gotchas §12: lightweight `v1.8.27` tag + `gh release create --latest`. That step is NOT complete at PR merge.
+
 ### Ship-fix-downstream-ignore-python-bytecode-2026-09-14
 
 - Feature shipped: **contributor PR #435 (issue #430, backlog #191) finished in place, with the owner's approval, after a week without response to review.** The deployed `.gitignore` block now carries `.agentcortex/**/__pycache__/`, so running the framework's own `validate.sh` no longer leaves bytecode for the banner's `git add .agentcortex/` to stage. The PR as submitted added repo-wide `__pycache__/` + `*.pyc` without `managed[]` entries: every re-deploy grew the adopter's file by 14 lines (measured 33 -> 47 -> 61), and the repo-wide pair also ignored the adopter's own bytecode. What shipped: scoped to the framework namespace (all 19 deployed `.py` are under `.agentcortex/tools/`), in `managed[]`, written last in the block. Contributor commit kept; no force-push.
@@ -187,7 +196,3 @@
 - Feature shipped: **a dangling `needs:` now fails a test instead of silently disabling every CI check.** GitHub rejects the *whole* workflow at parse time on an unresolvable `needs:` target — it does not skip the one job — so every push-triggered check stops running while the local tree stays green. A downstream fork hit exactly that on 2026-08-24 with `flutter analyze` 0, 9994 tests passing and `validate.sh` 0 warnings, because the branch was unpushed and nothing in the repo parses `.github/workflows/`. Here `test_security_workflow.py` already `yaml.safe_load`ed both workflows (so a YAML *syntax* error was caught) and pinned core job existence, but a dangling `needs:` is valid YAML and no test resolved the graph. Measured before the fix: `validate.yml` 12 jobs, `security.yml` 5 jobs, **0 dangling** — filed on a verified absence of a guard, not a live break (backlog #183).
 - **The guard globs rather than hard-codes, and the sequence form got a unit arm it could not otherwise earn.** It walks every `.github/workflows/*.yml|*.yaml`, so a third workflow is covered the day it lands — the two hard-coded paths in `test_security_workflow.py` would not have seen it. An empty file set or an empty jobs map FAILs rather than passing vacuously. The reason that matters: **every live `needs:` edge in this repo is the scalar form** (6 of them, all `'changes'`), so the `needs: [a, b]` branch has zero natural coverage and a half-blind normalizer would have read green forever; it is pinned directly instead. `yaml` arrives via `pytest.importorskip`, so an absent PyYAML reports SKIP rather than assurance.
 - Tests: **RED before GREEN on all three failure arms**, each mutated against the live tree and reverted in a `finally` — scalar dangling → exit 1 naming the job and missing target; sequence dangling → exit 1 through the list branch; a new `zz-tmp-red-probe.yml` with an empty `jobs:` → exit 1, which doubles as proof the glob picks up a workflow added *after* the test was written. `.github/` verified clean after each. `pytest tests/ci/test_ci_hardening.py tests/ci/test_security_workflow.py` **57 passed in 1.80s**; `check_text_integrity.py` passed with 0 baseline exceptions. One test file changed; no workflow, validator, deployed file, or governance surface touched, so ADR-006's new-check rules do not apply. The full local CI-equivalent suite was **not** run to completion — measured at ~35 tests / 15 min on this box — and PR CI is the authoritative full-suite evidence; stated rather than implied. SSoT sequence 164→165; Ship History rotated at cap 10 (`Ship-chore-v1.8.21-release-2026-08-14` → `archive/ship-history-2026.md`).
-
-### Ship-main-2026-08-27
-- Feature shipped: **v1.8.25 closes the release-to-downstream consistency gap.** Backlog #182 adds a pytest guard that derives the canonical version from `deploy.sh`, pins every release surface plus citation-date ordering, and was proved red against the v1.8.24 runtime-guide drift before repair. Companion backlog #180 excludes `.claude` from bare pytest discovery, eliminating duplicate collection from leftover agent worktrees. The adversarial premortem and clean-downstream reproduction are preserved in `docs/reviews/2026-08-26-govern-audit-release-downstream-premortem.md`; implementation commit `6984551`.
-- Tests: Pass — release consistency + deploy-manifest snapshot 3 passed; bare collection 916 tests / 0 errors; final post-archive validators and CI-equivalent suite recorded in `.agentcortex/context/archive/main-20260827.md`.
@@ -1,4 +1,4 @@
-# Testing Protocol v1.8.26
+# Testing Protocol v1.8.27
 
 > **This document guides the AI Agent to produce high-quality, trustworthy, and defensive test code.**
 

@@ -1,4 +1,4 @@
-# Testing Protocol (測試教戰守則) v1.8.26
+# Testing Protocol (測試教戰守則) v1.8.27
 >
 > **本文件旨在指引 AI Agent 產出高品質、可信任、且具備防禦性的測試程式碼。**