Study

CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.3] - 2026-04-19
+
+### Added
+- 新增 `verify-change` 受限环境回退能力：
+  - `--changed-files` 参数（支持逗号/分号/换行与 `@file`）
+  - 环境变量回退：`PSS_CHANGED_FILES` / `CODEX_CHANGED_FILES` / `CHANGED_FILES`
+  - 明确识别 `git-permission-denied (EPERM)` 场景
+- 新增 gate 变更集判定语义：`pre-commit-gate` / `pre-merge-gate` 仅对“changed files 命中的 warning”阻断。
+- 新增/补强多批 capability module 深度参考内容（AI / Infrastructure / DevOps / Review / Development / Architecture / Security / Data / Orchestration）。
+
+### Changed
+- `pre-* gate` 从“全仓质量 warning 即阻断”调整为“变更集命中 warning 才阻断”，历史质量债转为报告项。
+- `verify-change` changed file 输出统一为 target-relative 路径，降低 module/doc-sync 误判。
+- `personal-skill-system/docs` 主文档同步收敛到统一口径：
+  - `README.md`
+  - `ITERATION_HANDOFF.md`
+  - `CAPABILITY_MODULE_RATINGS.md`
+- `registry/capability-ratings.generated.json` 完成最终评级快照同步，`next-batch` 置空（当前快照无待晋升模块）。
+
+### Fixed
+- 修复 `capability-ratings.generated.json` BOM 导致的 Node `JSON.parse` 失败问题（统一为 UTF-8 无 BOM）。
+- 修复若干 handoff 文本段落中的收官数字与焦点描述不一致问题，确保 `58/0/0` 快照一致。
+
+### Capability Snapshot
+- TOP-ready: **58**
+- strong-but-not-top: **0**
+- thin: **0**
+- total rated capability modules: **58**
+
+### Verification
+- `node personal-skill-system/skills/tools/verify-skill-system/scripts/run.js --target personal-skill-system --json`
+  - `status: pass`
+  - `capabilityModules: 58`
+  - `routeEntries: 29`
+- Node JSON parse check:
+  - `capability-ratings.generated.json` parse ok
+
+### Suggested Commit Grouping (Release Packaging)
+1. `feat(pss-tooling): gate changed-file blocking and verify-change fallback chain`
+2. `feat(pss-capabilities): deepen AI/infra/devops/review modules`
+3. `feat(pss-capabilities): deepen development/architecture modules`
+4. `feat(pss-capabilities): deepen security/data/orchestration modules and close TOP-ready backlog`
+5. `docs(pss): sync README, ITERATION_HANDOFF, capability ratings and release notes`
+
 ## [2.0.9] - 2026-04-13
 
 ### Fixed

CLAUDE.md

@@ -1,137 +1,106 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+本文件面向在仓库内工作的 repo-aware agent 与维护者。目标只有一个：让后来接手的人不用靠猜。
 
-## Project Overview
+## 项目概览
 
-Code Abyss is an npm package that installs a "邪修红尘仙" persona configuration into Claude Code, Codex CLI, and Gemini CLI. It delivers: persona rules, 4 switchable output styles, 56 skill documents, and 5 executable verification/generation tools.
+Code Abyss 是一个多目标 AI CLI 安装器，负责把 persona、output styles、skills 与 optional packs 安装到：
 
-## Commands
+- `Claude Code`
+- `Codex CLI`
+- `Gemini CLI`
 
-```bash
-npm test                          # Run Jest test suite
-npm run verify:skills             # Validate all SKILL.md frontmatter contracts (fail-fast gate)
-node bin/install.js --help        # Installer CLI help
-node bin/install.js --target claude -y   # Zero-config install to ~/.claude/
-node bin/install.js --target codex -y    # Zero-config install to ~/.codex/
-node bin/install.js --target gemini -y   # Zero-config install to ~/.gemini/
-node bin/install.js --list-styles        # List available output styles
-```
-
-Running individual verify tools directly:
-```bash
-node skills/tools/verify-security/scripts/security_scanner.js <path>
-node skills/tools/verify-module/scripts/module_scanner.js <path>
-node skills/tools/verify-change/scripts/change_analyzer.js --mode staged|working
-node skills/tools/verify-quality/scripts/quality_checker.js <path>
-node skills/tools/gen-docs/scripts/doc_generator.js <path>
-```
-
-Running a single test file:
-```bash
-npx jest test/install-registry.test.js --runInBand
-```
+仓库不是“文档仓”或“提示词仓”，而是一个带测试、schema、runtime 约束的安装分发仓。
 
-CI runs on Node 18/20/22: `npm ci && npm test && npm run verify:skills` plus all 4 verify tools + smoke install/uninstall on 3 platforms.
+## 先看哪些文件
 
-## Architecture
+### 入口
 
-### Three-Layer System
+- `bin/install.js`
+- `bin/packs.js`
+- `bin/adapters/claude.js`
+- `bin/adapters/codex.js`
+- `bin/adapters/gemini.js`
 
-| Layer | Source | Purpose |
-|-------|--------|---------|
-| Identity & Rules | `config/CLAUDE.md` | Persona, rules, scene routing, execution chains |
-| Output Style | `output-styles/*.md` + `index.json` | Style registry + per-style templates |
-| Knowledge | `skills/**/*.md` | Domain skill documents + executable tools |
+### 单一事实源
 
-`config/AGENTS.md` remains a repository snapshot, but Codex runtime installation no longer writes a generated `~/.codex/AGENTS.md`. Codex now runs in a `skills-only` shape and installs Code Abyss plus gstack under `~/.agents/skills/`.
+- `skills/**/SKILL.md`
+- `output-styles/index.json`
+- `config/personas/index.json`
+- `packs/*/manifest.json`
+- `.code-abyss/packs.lock.json`
 
-### Skill Registry (Single Source of Truth)
+### 回归测试
 
-`bin/lib/skill-registry.js` is the authoritative skill discovery engine for installed skills, `run_skill.js`, Claude command generation, and CI validation.
+- `test/install-smoke.test.js`
+- `test/style-registry.test.js`
+- `test/pack-registry.test.js`
+- `test/packs-cli.test.js`
+- `test/docs-drift.test.js`
 
-- Each skill's metadata lives in `skills/**/SKILL.md` YAML frontmatter
-- Required fields: `name` (kebab-case slug), `description`, `user-invocable`
-- Optional fields: `allowed-tools` (default: `Read`), `argument-hint`, `aliases`
-- `category` is auto-inferred from directory prefix (`tools/` → tool, `domains/` → domain, `orchestration/` → orchestration)
-- `runtimeType` is auto-inferred: `scripts/` has exactly one `.js` → `scripted`, else `knowledge`
-- Registry fail-fast validates: missing fields, bad slugs, illegal tool names, duplicate names, multiple script entries
+## 常用命令
 
-### Pack Registry
-
-`packs/*/manifest.json` defines installable packs. `abyss` is the core pack; `gstack` is a pinned upstream pack consumed by the Claude/Codex auto-install flows. `bin/lib/pack-registry.js` is the source of truth for host file mappings and upstream metadata.
-
-Project-level automatic pack sync is driven by `.code-abyss/packs.lock.json`. The installer reads the nearest lock file from the current working directory upward and installs host-specific packs according to `required`, `optional`, `optional_policy`, and `sources`. `node bin/packs.js bootstrap` initializes the lock plus README/CONTRIBUTING snippets, `--apply-docs` writes them back into repo docs, `vendor-pull` / `vendor-sync` manage local sources, `vendor-sync --check` acts as a gate, `report summary` reads `.code-abyss/reports/`, and `uninstall <pack>` removes pack-specific runtime artifacts with a report.
-
-### Style Registry
-
-`bin/lib/style-registry.js` manages `output-styles/index.json`. Exactly one style must be `default`. Each style has `slug`, `label`, `description`, `file`, `targets`, `default`.
+```bash
+npm test
+npm run verify:skills
 
-### Dual-Target Generation
+node bin/install.js --help
+node bin/install.js --list-styles
+node bin/install.js --list-personas
 
-The installer generates different artifacts per target CLI:
+npm run packs:check
+npm run packs:diff
+npm run packs:report -- summary
+```
 
-- **Claude**: `~/.claude/commands/*.md` (slash commands) — `runtimeType=scripted` calls `run_skill.js`, `knowledge` reads SKILL.md directly
-- **Codex**: `~/.agents/skills/**/SKILL.md` — Codex discovers user skills from `~/.agents/skills`; Code Abyss auto-installs an embedded gstack runtime under `~/.agents/skills/gstack`
-- **Gemini**: `~/.gemini/GEMINI.md` + `~/.gemini/commands/*.toml` + `~/.gemini/skills/**/SKILL.md` — Gemini reads persistent context from `GEMINI.md` and custom commands from TOML files
+## 修改时的规则
 
-Claude command generation and Codex skill installation share the same skill source tree; only Claude filters on `user-invocable` to emit slash commands.
+### 改 skill
 
-### Adapter Pattern
+- 修改 `skills/**/SKILL.md` 时，把 frontmatter 当作唯一元数据入口。
+- 如果是脚本型 skill，只允许一个 `scripts/*.js` 入口。
+- 改完至少跑 `npm run verify:skills`。
 
-`bin/install.js` is the orchestration layer. Target-specific logic lives in adapters:
-- `bin/adapters/claude.js` — Claude auth detection, settings merge, core files mapping
-- `bin/adapters/codex.js` — Codex auth detection, config.toml merge, core files mapping
-- `bin/lib/ccstatusline.js` — Claude status bar (ccstatusline) integration
-- `bin/lib/style-registry.js` — Style catalog + repository AGENTS snapshot assembly
-- `bin/lib/utils.js` — Shared: `copyRecursive`, `rmSafe`, `deepMergeNew`, `parseFrontmatter`, `shouldSkip`
+### 改 style / persona
 
-### Skill Execution
+- style registry 在 `output-styles/index.json`
+- persona registry 在 `config/personas/index.json`
+- 改 registry 时同步确认默认项只有一个
+- 改完至少跑 `test/style-registry.test.js`
 
-`skills/run_skill.js` is the script-type skill runner:
-1. Resolve skill via registry → validate `runtimeType=scripted`
-2. Acquire target lock (async polling, 30s timeout)
-3. Spawn child process with the script entry
-4. Propagate exit code, release lock on exit/signal
+### 改安装流程
 
-Knowledge-type skills are read-only — no script execution, just load SKILL.md content.
+- 优先读 `bin/install.js` 的 orchestration，再读 target adapter
+- 不要凭文档猜目标目录，以 target registry、manifest、smoke tests 为准
+- 涉及 Claude / Codex / Gemini 产物变化时，回看 `test/install-smoke.test.js`
 
-## Key Contracts
+### 改 pack
 
-### SKILL.md Frontmatter
+- `packs/*/manifest.json` 描述 pack 契约
+- `.code-abyss/packs.lock.json` 描述项目级启用策略
+- `bin/packs.js` 管 bootstrap、vendor、report、uninstall
+- 改完至少跑 `npm run packs:check`
 
-```yaml
----
-name: verify-quality          # kebab-case, unique across all skills
-description: Code quality gate
-user-invocable: true           # false = knowledge-only, not exposed as Claude slash command
-allowed-tools: Bash, Read, Glob  # optional, default: Read
-argument-hint: <scan-path>     # optional
-aliases: vq                    # optional comma-separated aliases
----
-```
+### 改文档
 
-### Adding a New Skill
+- 不要手写容易漂移的技能数量、历史入口数量
+- 文档中的路径、命令、生成物必须能在源码或测试里找到对应依据
+- `README.md`、`DESIGN.md`、`docs/*.md` 改动后，至少跑 `test/docs-drift.test.js`
 
-1. Create `skills/<category>/<skill-name>/SKILL.md` with required frontmatter
-2. For script-type: add exactly one `scripts/<name>.js` entry point
-3. Run `npm run verify:skills` — must pass with zero errors
-4. Run `npm test` — especially `test/install-registry.test.js`, `test/install-generation.test.js`, `test/run-skill.test.js`
-5. Verify no name collision with existing skills
+## 当前实现口径
 
-### Style Contract
+- Claude：写入 `~/.claude/CLAUDE.md`、`commands/`、`skills/`、`settings.json`
+- Codex：写入 `~/.codex/config.toml`、`instruction.md`、`AGENTS.md`、`skills/`，pack runtime 可写入 `~/.agents/skills/`
+- Gemini：写入 `~/.gemini/GEMINI.md`、`commands/*.toml`、`skills/`、`settings.json`
 
-- Exactly one entry in `output-styles/index.json` must have `default: true`
-- `slug` must be kebab-case, unique
-- `targets` defaults to `["claude", "codex"]` if omitted
-- Corresponding `.md` file must exist in `output-styles/`
+## 文档阅读顺序
 
-## Install Targets
+1. `README.md`
+2. `docs/ONBOARDING.md`
+3. `DESIGN.md`
+4. `docs/PACK_SYSTEM.md`
+5. `docs/SKILL_AUTHORING.md`
 
-| Target | Config file | Skill artifacts | Style mechanism |
-|--------|-------------|-----------------|-----------------|
-| Claude | `~/.claude/CLAUDE.md` | `~/.claude/commands/*.md` + `~/.claude/skills/` | `settings.json.outputStyle` = slug |
-| Codex | `~/.codex/config.toml` | `~/.agents/skills/` + `~/.agents/skills/gstack/` | Skills-only runtime; no generated AGENTS.md |
-| Gemini | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` + `~/.gemini/commands/*.toml` + `~/.gemini/skills/` | Global context + TOML command runtime |
+## 一句判断标准
 
-Backups go to `<target-dir>/.sage-backup/` with `manifest.json`. Uninstall restores from backup.
+如果一个新人读完 README 和 onboarding 之后，依旧不知道应该先跑什么命令、看什么文件、怎样验证改动，这份文档就是不合格的。