docs(issue-222): align skill-surface docs and final outcomes

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.3.8 - 2026-03-04
+
+### Added
+
+- Final outcomes artifact at `docs/plans/skills-review-final-outcomes.md` with auditable keep/remove decisions and explicit migration mapping
+  for removed entrypoints.
+
+### Changed
+
+- Repo-level docs were aligned to the finalized skill/check surface, including canonical `scripts/check.sh` gates and entrypoint-drift guards
+  in `PROJECT_DEV_WORKFLOW.md`.
+- `README.md` structure notes now reflect current tracked directories and remove stale progress-log wording.
+- `docs/testing/script-smoke.md` plan-issue cleanup example now uses the current `<owner__repo>` workspace slug convention.
+
 ## v2.3.7 - 2026-03-04
 
 ### Added

README.md

@@ -10,10 +10,10 @@ agent-kit tracks AI agent setup to keep workflows consistent across machines. It
 .
 ├── .github/    # CI workflows (GitHub Actions)
 ├── prompts/    # prompt presets
-├── skills/     # skills (tools/, workflows/, automation/, .system/, _shared/, _projects/, openai/)
+├── skills/     # skills (tools/, workflows/, automation/, .system/, _shared/, _projects/)
 ├── scripts/    # loader + helper scripts
 ├── docker/     # Docker images + env tooling
-├── docs/       # docs, templates, progress logs
+├── docs/       # runbooks, plans, and testing docs
 ├── tests/      # pytest regression/smoke tests
 └── AGENTS.md   # global agent rules (response/tooling)
 ```

docs/plans/skills-review-final-outcomes.md

@@ -0,0 +1,38 @@
+# Skills Review Final Outcomes
+
+## Final Outcomes
+
+- Repository-level docs now describe the canonical check surface (`scripts/check.sh` modes plus
+  entrypoint drift guards) without legacy wrapper guidance.
+- Runtime path examples for plan-issue cleanup now use the current `<owner__repo>` workspace slug convention.
+- The retained skill entrypoint surface is documented and auditable through current `SKILL.md`, smoke specs, and regression checks.
+
+| Surface | Decision | Outcome |
+| --- | --- | --- |
+| `scripts/check.sh --all` | keep | Canonical full local validation gate for lint, docs freshness, contracts, and tests. |
+| `bash scripts/ci/stale-skill-scripts-audit.sh --check` | keep | Required drift guard when workflow/tool entrypoints are added, removed, or renamed. |
+| `scripts/check.sh --entrypoint-ownership` | keep | Required ownership gate for workflow/tool entrypoint references. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh` | keep | Retained release-guide resolution entrypoint. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | keep | Retained release publish entrypoint. |
+| `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh` | remove | Legacy wrapper removed; notifier surface remains `desktop-notify.sh` and `project-notify.sh`. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` | remove | Legacy release helper removed in favor of the consolidated publish entrypoint. |
+
+## Removed Entrypoints
+
+- `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh`
+- `$AGENT_HOME/skills/automation/release-workflow/scripts/audit-changelog.zsh`
+- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh`
+- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-find-guide.sh`
+- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-notes-from-changelog.sh`
+- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-scaffold-entry.sh`
+
+## Migration Mapping
+
+| Old Entrypoint | Replacement | Notes |
+| --- | --- | --- |
+| `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh` | `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/project-notify.sh` | Use project-scoped title wrapper for notification publishing. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/audit-changelog.zsh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Audit behavior is folded into the consolidated publish command. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Publish command handles changelog audit + release body verification. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-find-guide.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .` | Guide/template resolution is now a single public entrypoint. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-notes-from-changelog.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Release note extraction now happens in the consolidated publish path. |
+| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-scaffold-entry.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Scaffolding and publish path are unified under one release command. |

docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md

@@ -17,6 +17,9 @@
 - Canonical pre-commit gate: `scripts/check.sh --all`
 - Docs freshness gate (standalone): `scripts/check.sh --docs`
 - CI parity guard: `scripts/check.sh --tests -- -k parity -m script_regression`
+- Skill entrypoint drift guard (when workflow/tool entrypoints change):
+  - `bash scripts/ci/stale-skill-scripts-audit.sh --check`
+  - `scripts/check.sh --entrypoint-ownership`
 
 Use `scripts/check.sh` modes for project-dev verification. Avoid reintroducing ad-hoc legacy script wrappers in docs/workflows.
 

docs/testing/script-smoke.md

@@ -66,7 +66,7 @@ Run the cleanup helper before declaring plan completion:
 
 ```bash
 scripts/check_plan_issue_worktree_cleanup.sh \
-  "$AGENT_HOME/out/plan-issue-delivery/graysurf-agent-kit/issue-193/worktrees"
+  "$AGENT_HOME/out/plan-issue-delivery/graysurf__agent-kit/issue-193/worktrees"
 ```
 
 Expected behavior: