oh-my-customcodex 0.5.20 → 0.5.22

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-50 agents. 121 skills. 22 rules. One command.
+50 agents. 122 skills. 23 rules. One command.
 
 ```bash
 npm install -g oh-my-customcodex && cd your-project && omcustomcodex init
@@ -135,13 +135,13 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (121)
+### Skills (122)
 
 | Category | Count | Includes |
 |----------|-------|----------|
 | Best Practices | 24 | Go, Python, TypeScript, Kotlin, Rust, React, FastAPI, Spring Boot, Django, Flutter, Docker, AWS, Postgres, Redis, Kafka, dbt, Spark, Snowflake, Airflow, pipeline-architecture-patterns, alembic, and more |
 | Routing | 4 | secretary, dev-lead, de-lead, qa-lead |
-| Workflow | 13 | structured-dev-cycle, deep-plan, research, evaluator-optimizer, dag-orchestration, worker-reviewer-pipeline, reasoning-sandwich, pipeline, and more |
+| Workflow | 14 | structured-dev-cycle, deep-plan, research, evaluator-optimizer, dag-orchestration, worker-reviewer-pipeline, reasoning-sandwich, pipeline, fsd, and more |
 | Development | 10 | dev-review, dev-refactor, analysis, create-agent, intent-detection, web-design-guidelines, omcodex:takeover, skill-extractor, pre-generation-arch-check, idea |
 | Operations | 10 | update-docs, audit-agents, sauron-watch, monitoring-setup, token-efficiency-audit, fix-refs, release-notes, and more |
 | Memory | 3 | memory-save, memory-recall, memory-management |
@@ -172,6 +172,7 @@ All commands are invoked inside the oh-my-customcodex GPT Codex + OMX session.
 | `/pre-generation-arch-check` | Check architecture risks before implementation |
 | `/adversarial-review` | Attacker-mindset security code review |
 | `/omcustomcodex:goal` | Keep a concrete objective in view through planning, execution, and verification |
+| `/omcustomcodex:fsd` | Full Self Driving release loop: repeat `/pipeline auto-dev` + `/homework` until eligible issues are exhausted |
 | `/pipeline` | Execute YAML-defined pipelines |
 | `/pipeline resume` | Resume a halted pipeline from last failure point |
 
@@ -217,15 +218,15 @@ All commands are invoked inside the oh-my-customcodex GPT Codex + OMX session.
 
 ---
 
-### Rules (22)
+### Rules (23)
 
 | Priority | Count | Purpose |
 |----------|-------|---------|
 | **MUST** | 14 | Safety, permissions, agent design, identification, orchestration, verification, completion, enforcement |
-| **SHOULD** | 6 | Interaction, error handling, memory, HUD, ecomode, ontology routing |
+| **SHOULD** | 7 | Interaction, error handling, memory, HUD, ecomode, ontology routing, verification ladder |
 | **MAY** | 1 | Optimization |
 
-Key rules: R010 (orchestrator never writes files), R009 (parallel execution mandatory), R017 (sauron verification before push), R020 (completion verification before declaring done), R021 (advisory-first enforcement model).
+Key rules: R010 (orchestrator never writes files), R009 (parallel execution mandatory), R017 (sauron verification before push), R020 (completion verification before declaring done), R021 (advisory-first enforcement model), R023 (verification ladder).
 
 ---
 
@@ -281,14 +282,14 @@ your-project/
 ├── AGENTS.md                   # Entry point
 ├── .codex/
 │   ├── agents/                 # 50 agent definitions
-│   ├── rules/                  # 22 governance rules (R000-R021)
+│   ├── rules/                  # 23 governance rules (R000-R023)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
 ├── .agents/
-│   └── skills/                 # 121 installed skill modules
+│   └── skills/                 # 122 installed skill modules
 └── guides/                     # 52 reference documents
 ```
 

package/dist/cli/index.js

@@ -3091,7 +3091,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.5.20",
+    version: "0.5.22",
     requiresCC: ">=2.1.121",
     claudeCode: {
       minimumVersion: "2.1.121",
@@ -26418,6 +26418,17 @@ function isCacheFresh(cache, now, cacheTtlMs) {
   }
   return now - checkedAt < cacheTtlMs;
 }
+function readFreshPlausibleCachedVersion(cachePath, currentVersion, now, cacheTtlMs) {
+  const cache = readCache(cachePath);
+  if (!cache || !isCacheFresh(cache, now, cacheTtlMs)) {
+    return null;
+  }
+  const cachedVersion = normalizeVersion(cache.latestVersion);
+  if (!cachedVersion || !isVersionPlausible(currentVersion, cachedVersion)) {
+    return null;
+  }
+  return cachedVersion;
+}
 function fetchLatestVersionFromNpm(packageName = DEFAULT_PACKAGE_NAME) {
   try {
     const output = execSync2(`npm view ${packageName} version --json`, {
@@ -26534,7 +26545,8 @@ function executeSelfUpdate(options = {}) {
   if (!options.silent) {
     console.log(i18n.t("cli.selfUpdate.updatingGlobal", { version: latestVersion }));
   }
-  const installed = installGlobalPackage(packageName, latestVersion, options.silent ?? false);
+  const installPackage = options.installPackage || installGlobalPackage;
+  const installed = installPackage(packageName, latestVersion, options.silent ?? false);
   if (installed) {
     if (!options.silent) {
       console.log(i18n.t("cli.selfUpdate.updated", { version: latestVersion }));
@@ -26563,20 +26575,13 @@ function checkSelfUpdate(options) {
       reason: "invalid-current-version"
     };
   }
-  let latestVersion = null;
-  let usedCache = false;
-  const cache = readCache(cachePath);
-  if (cache && isCacheFresh(cache, now, cacheTtlMs)) {
-    const cachedVersion = normalizeVersion(cache.latestVersion);
-    if (isVersionPlausible(currentVersion, cachedVersion)) {
-      latestVersion = cachedVersion;
-      usedCache = true;
-    }
-  }
+  let latestVersion = readFreshPlausibleCachedVersion(cachePath, currentVersion, now, cacheTtlMs);
+  const usedCache = Boolean(latestVersion);
   if (!latestVersion) {
     const fetched = fetchLatestVersion(packageName);
-    if (fetched && isVersionPlausible(currentVersion, fetched)) {
-      latestVersion = fetched;
+    const fetchedVersion = fetched ? normalizeVersion(fetched) : "";
+    if (fetchedVersion) {
+      latestVersion = fetchedVersion;
       writeCache(cachePath, latestVersion, now);
     }
   }

package/dist/index.js

@@ -2316,7 +2316,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.5.20",
+  version: "0.5.22",
   requiresCC: ">=2.1.121",
   claudeCode: {
     minimumVersion: "2.1.121",

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.5.20",
+  "version": "0.5.22",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",

package/templates/.claude/rules/MUST-agent-design.md

@@ -24,11 +24,10 @@ tools: [Read, Write, ...]  # Allowed tools
 | `opus` | claude-opus-4-6 | Complex reasoning, architecture |
 | `opusplan` | claude-opus-4-6 + plan mode | Architecture planning with approval gates |
 | `opus47` | claude-opus-4-7 | Latest Opus model, supports xhigh effort |
-
 Extended context suffix: `[1m]` (e.g., `claude-opus-4-6[1m]`) — enables 1M token context window.
 
 <!-- DETAIL: Fallback Models and Thinking Toggle (Claude Code v2.1.166+)
-Claude compatibility settings can declare up to three `fallbackModel` entries tried in order when the primary Claude model is overloaded or unavailable. `--fallback-model` also applies to interactive Claude sessions. Treat this as platform availability failover, not Codex-native model routing or outcome-based escalation. Claude Code v2.1.166+ also supports disabling default thinking with `MAX_THINKING_TOKENS=0`, `--thinking disabled`, or the per-model thinking toggle. Codex-native agents continue to use the OMX model contract and `reasoning_effort` routing.
+Claude compatibility settings can declare up to three `fallbackModel` entries tried in order when the primary Claude model is overloaded or unavailable. `--fallback-model` also applies to interactive Claude sessions. Treat this as platform availability failover, not Codex-native model routing or outcome-based escalation. Claude Code v2.1.166+ also supports disabling default thinking with `MAX_THINKING_TOKENS=0`, `--thinking disabled`, or the per-model thinking toggle. Claude Code v2.1.169+ adds `--safe-mode` / `CLAUDE_CODE_SAFE_MODE` to disable customizations for regression isolation, plus `disableBundledSkills` / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` to hide bundled skills/workflows/slash commands when they conflict with project skills. Codex-native agents continue to use the OMX model contract and `reasoning_effort` routing.
 -->
 
 ### Optional Frontmatter
@@ -88,6 +87,8 @@ This Codex port ships `.claude` compatibility templates. When updating those tem
 - v2.1.162: `claude agents --json` includes waiting/blocker metadata and explicit `--tools Grep/Glob` behavior is fixed; compatibility prompts may use those fields when diagnosing stuck Claude sessions.
 - v2.1.163: managed `requiredMinimumVersion`/`requiredMaximumVersion`, `/plugin list`, Stop/SubagentStop `hookSpecificOutput.additionalContext`, and skill command literal `\$` escaping are available. Hook/skill template changes should preserve these affordances.
 - v2.1.165: bug-fix/reliability release; no local template change required beyond compatibility confirmation. v2.1.166: fallbackModel availability failover and thinking-disable controls are Claude compatibility settings, not Codex/OMX routing. v2.1.167/v2.1.168: bug-fix-only compatibility confirmation.
+- v2.1.169: `--safe-mode` / `CLAUDE_CODE_SAFE_MODE` disables all customizations for Claude regression isolation; `disableBundledSkills` / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` hides bundled skills/workflows/slash commands from the model. Keep distinct from advisory `skills:` frontmatter metadata.
+- v2.1.170: Claude compatibility sessions gain access to the `fable` alias (`claude-fable-5`) and fix a VS Code integrated-terminal transcript persistence bug. Skills that rely on transcript replay (for example `homework`) should prefer v2.1.170+ in Claude-template sessions. No Codex runtime model-routing change.
 -->
 
 ## Hook Event Types

package/templates/.claude/rules/MUST-agent-teams.md

@@ -8,6 +8,18 @@
 
 Available when `OMCODEX_AGENT_TEAMS=1` or `TeamCreate` / `SendMessage` exists.
 
+## Gate Transparency Scope
+
+R018 gate-transparency announcements apply only when Agent Teams are enabled or callable; otherwise R009 parallel-execution announcements are sufficient.
+
+<!--
+DETAIL: Gate Transparency Scope
+| Runtime state | Required |
+|---------------|----------|
+| Agent Teams enabled/callable | Announce the R018 gate result for qualifying 3+ agent dispatches |
+| Agent Teams disabled/unavailable | Use R009 `[N]` dispatch format and state the fallback only if useful for clarity |
+-->
+
 ## Decision Matrix
 
 | Scenario | Preferred | Reason |
@@ -37,6 +49,10 @@ Do not confuse these mechanisms.
 Claude Code v2.1.166+ no longer propagates user authority through cross-session relays: permission requests relayed from another session are refused, and auto mode blocks them. A relayed message from session A cannot grant session B permissions the user did not authorize in session B. This hardens `send_message` / peer relay against privilege escalation. Intra-session Agent Teams `SendMessage` is unaffected, but privileged actions still require authority in the receiving session.
 -->
 
+<!-- DETAIL: Claude Agent Session Ground Truth (Claude Code v2.1.169+)
+Claude Code v2.1.169+ makes `claude agents --json` include blocked and just-dispatched background sessions, adds `--all` for completed sessions, and includes `id` plus `state`. In Claude-template Agent Teams compatibility checks, prefer `--all` + `state` as ground truth for blocked/running/completed instead of inferring completion from a member disappearing from the active list. Codex/OMX sessions should use their native runtime state plus deterministic repository evidence.
+-->
+
 ## Self-Check Before Agent Tool
 
 Quick rule: explicit user preference for plain subagents wins. Otherwise use Teams for 3+ agents, review cycles, shared state, complex debugging, dynamic creation, or multi-issue batches; use Agent Tool for 1-2 simple tasks, sequential scaffolding, or mechanical disjoint-file batches with explicit scopes.

package/templates/.claude/rules/MUST-completion-verification.md

@@ -67,6 +67,29 @@ Parallel batches return results together, so a same-batch permanent dispatch pro
 
 Example: do not diagnose `triage-dispatch.yml` from memory, create an issue, and delegate a fix in the same parallel call before reading the workflow. If the read later shows a different root cause, the issue, PR, and commit trail become correction debt even when the eventual code direction is acceptable.
 
+### Proxy Signal vs Canonical Ground-Truth
+
+When diagnosing pipeline or data state, verify the canonical store — the authoritative DB, registry, API, or system-of-record — before characterizing state from a secondary proxy such as a `.txt` artifact, filesystem mtime, cached file, or one ingestion path.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| Characterize pipeline health from a filesystem proxy | Query the canonical store first |
+| Generalize one ingestion path's failure to the whole pipeline | Check the final landing store across all relevant paths before alarming or reprocessing |
+
+A single path's failure does not prove the whole multi-path system is down.
+
+## Config-Schema-Before-Edit
+
+Before planning edits to configuration that participates in an override, precedence, inheritance, provider, endpoint, credential, or multi-key chain, read the full config schema and precedence chain first. Do not plan partial edits before understanding which fields override which.
+
+This applies when a change touches interdependent fields such as provider + `base_url`, endpoint overrides, multi-key fallback, or layered defaults. A single independent field edit does not require a full-schema read.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| Plan a provider/endpoint switch as N commands without reading the override chain | Read schema and precedence → enumerate every touched field, including `base_url` → then plan |
+
+Sibling discipline to Read-Before-Characterize: diagnosis must read evidence before labeling; config edits must read precedence before planning.
+
 ## Degraded-Output Re-Verification Gate
 
 When tool output shows provider instability, buffering, truncation, duplicated chunks, `529`, timeout recovery, or `(no result)` while a permanent action is being considered, treat the current read as degraded. Do not characterize corruption, missing files, stale state, release failure, or data loss from that single degraded read.
@@ -164,6 +187,17 @@ When a user sends a new instruction while work is in progress, completion status
 3. If the new message adds a requirement, add it to the completion contract before closing.
 4. If no conflict exists, continue but explicitly preserve the new requirement in the next verification pass.
 
+### Interrupt ≠ Prior-Request Cancellation
+
+If the first message after an interrupt is ambiguous, do not assume the prior request was cancelled. The user may be continuing a multi-message request, correcting input, or starting a new request. Keep the prior non-destructive context alive and ask once only when the new message cannot be classified as a clear instruction.
+
+**Safety carve-out:** if the interrupted work is destructive or irreversible (`git reset --hard`, `git clean -fd`, broad `rm`, force push, tunnel/DNS/k8s/infra deletion, production state changes), halt first and require explicit re-authorization before resuming. Interrupts retain their emergency-stop value for risky work.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| Treat an ambiguous interrupt as cancellation and switch to unrelated work | Preserve context and clarify intent once |
+| Continue destructive work after an ambiguous interrupt | Stop immediately; resume only after explicit re-authorization |
+
 ### Tool-Call Payload Completeness
 
 도구 호출의 required 파라미터는 invoke 전에 확인한다(완료 선언 후가 아니라 호출 시점의 전제조건). announce(prefix)만 출력하고 payload의 required 필드를 누락하는 패턴은 R008 "Required-Parameter Completeness Check"가 canonical owner다. Reference: #1487 / upstream #1324.
@@ -212,6 +246,30 @@ Related memory records:
 - `feedback_subagent_pre_existing_claims.md` — subagent false-positive pattern
 -->
 
+## CI Publish-Step Error vs Published-Artifact Ground Truth
+
+A CI publish/deploy step that logs an error has not necessarily failed. The step may recover through a fallback or the error may be non-fatal. Before declaring a publish/release failed, re-running it, rolling it back, or changing release workflow logic, verify the published artifact directly.
+
+| Publish target | Ground-truth check |
+|----------------|--------------------|
+| npm | `npm view <pkg> version` equals expected |
+| GitHub Release | `gh release view <tag>` exists and is not draft |
+| Docker/registry image | image tag or manifest exists |
+| Run outcome | `gh run view <id> --json jobs` conclusions, not one step log line |
+
+## State-Change Claim → Live System Verification
+
+Before closing or marking-done a task that claims an infrastructure/resource state change, verify the actual live system state rather than only the command attempt.
+
+| Claimed state change | Live ground-truth check |
+|----------------------|-------------------------|
+| Service stopped | `launchctl list`, `systemctl status`, or equivalent shows inactive/absent |
+| k8s resource torn down | `kubectl get <resource>` returns NotFound |
+| Container removed | `docker ps -a` does not list it |
+| Process killed | `pgrep`/`ps` check returns empty |
+
+"Issued the teardown" is not evidence that the resource is down.
+
 ## Integration
 
 | Rule | Interaction |

package/templates/.claude/rules/MUST-intent-transparency.md

@@ -73,6 +73,19 @@ R001-listed catastrophic git operations (`git reset --hard`, `git clean -fd`, `g
 
 Boundary: this rule governs model behavior only. It cannot suppress Codex/Claude runtime auto-mode permission prompts. For genuine prompt suppression on a repeated destructive command, surface the scoped settings/permission-rule workaround for the specific command instead of re-asking the same high-level question.
 
+## User-Provided Input Precedence
+
+When the user explicitly provides new input (credentials, config values, IdP, API keys, endpoints), applying that new input takes precedence over idempotent "reuse existing" logic. After applying, verify the change took effect using only non-secret identifiers such as `client_id`, endpoint URL, key fingerprint/last-4, or a side-effect probe. Never echo secret values into the transcript.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| "An existing X is present → reuse it" when the user just supplied a new X | Apply the user-supplied X; reuse only when the user supplied nothing |
+| User-supplied X equals the existing X | Treat as an idempotent no-op; do not re-provision |
+| User supplies only a subset of fields | Apply supplied fields; reuse existing values only for unsupplied fields |
+| Apply new credential, assume it took effect | Verify via non-secret identifier match or side-effect probe |
+
+Cross-reference: R001 credential guardrails and R020 actual-outcome verification.
+
 ## Structured Question Failure Discipline
 
 When a structured question surface (`AskUserQuestion`, `omx question`, or native structured input) is rejected, unavailable, or malformed, the orchestrator must not silently downgrade to a different workflow.

package/templates/.claude/rules/MUST-parallel-execution.md

@@ -210,6 +210,19 @@ When announcing a parallel dispatch in prose text (not the Agent tool call itsel
 The list form mirrors the tool-call `[N]` prefix pattern and scales better to 3+ concurrent agents.
 -->
 
+<!--
+DETAIL: Parallel Feature Integration Gate
+
+## Parallel Feature Integration Gate
+
+When parallel feature agents edit interdependent code, isolated passes are not enough: run aggregate build plus runtime/smoke verification on the merged worktree before declaring done.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| Accept each subagent's isolated pass as release-ready | Re-run aggregate verification on the merged worktree |
+| Skip runtime smoke because every file-domain lane passed | Smoke the integrated feature path or device/browser/app surface |
+-->
+
 ## Result Aggregation
 
 ```

package/templates/.claude/rules/MUST-safety.md

@@ -17,6 +17,23 @@
 - Do not rotate, delete, recreate, or replace credentials unless the user explicitly requested that exact credential action.
 - Before irreversible action on shared infrastructure or credentials, reconfirm the target, namespace/account/project, requested scope, rollback path, and user authorization.
 - Stop instead of chaining privileged actions when the next step would affect a different credential, tunnel, namespace, pod, cluster, account, or shared service than the user requested.
+- When a credential/token is needed, ask for the specific value or file before running blind discovery scans (`env | grep`, repo-wide token greps, credential-store dumps). If a classifier blocks a credential action once while a standing user-deny is active, switch to a user-runs command and do not retry by another mechanism.
+
+### Standing User-Deny + Classifier Block
+
+When the user has a standing "do not touch X" constraint and a safety classifier blocks an action on X once, immediately switch to a user-runs command/instruction path. Do not retry the blocked edit, scan, or credential action via another mechanism.
+
+### Infra-Diagnostic File Checks — Metadata, Not Contents
+
+When diagnosing infrastructure or health issues (502s, container state, env/config presence), file checks must stay metadata-only: `ls -la` for existence, size, permissions, and mtime. Do not `cat .env`, inspect credential JSON keys, parse secret-bearing files, or read secret contents into the transcript just to confirm configuration exists.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| `cat .env` / inspect OAuth or credential keys during a health diagnosis | `ls -la .env` or request the exact value from the user if genuinely needed |
+
+### Infra/Resource Deletion Blast Radius
+
+Before deleting shared infrastructure resources (tunnels, DNS records, k8s resources, load balancers, security groups), enumerate every endpoint, route, selector, target, or rule served by that resource — not only the hostname or object the user named. Prefer reversible disable/detach/stop actions when they satisfy the task.
 
 ## Required Before Destructive Operations
 

package/templates/.claude/rules/SHOULD-interaction.md

@@ -26,6 +26,9 @@
 | Clear | Execute immediately |
 | Ambiguous | `[Confirm] Understood "{request}" as {interpretation}. Proceed?` |
 | Risky | `[Warning] This action has {risk}. Continue? Yes: {action} / No: Cancel` |
+| Interrupt (ambiguous first message) | Do not assume the prior request is cancelled. The first message after an interrupt may be continuation, correction, or a new request. If the in-progress action is risky/destructive, apply the Risky row first and halt before clarification. |
+
+Request handling precedence: **Risky > Interrupt > Ambiguous > Clear**. Clear new instructions should still be executed directly; the interrupt row exists only for ambiguous first messages after an interruption.
 
 ## External Product UI Claims
 

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -22,6 +22,20 @@ Agent frontmatter `memory: project|user|local` enables persistent memory:
 | `project` | `.codex/agent-memory/<name>/` | Yes |
 | `local` | `.codex/agent-memory-local/<name>/` | No |
 
+<!--
+DETAIL: Project memory root guard
+
+## Subagent `memory: project` Source-Tree Pollution Guard
+
+A subagent working from a subdirectory must not create nested `.codex/agent-memory/` or `.claude/agent-memory/` directories inside source packages.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| Accept nested `src/**/.codex/agent-memory/` or `src/**/.claude/agent-memory/` created by a worker | Verify memory writes land at project-root `.codex/` (or template-root `.claude/` for compatibility) and remove nested memory directories before commit |
+
+Before committing subagent work, check for nested memory pollution with a targeted search such as `find . \\( -path '*/src/*/.codex/agent-memory' -o -path '*/src/*/.claude/agent-memory' \\) -print`.
+-->
+
 ## When to Use Searchable MCP Memory
 
 | Scenario | Native | AgentMemory-compatible / omx-memory |

package/templates/.claude/rules/SHOULD-verification-ladder.md

@@ -0,0 +1,124 @@
+# [SHOULD] Verification Ladder Rules
+
+> **Priority**: SHOULD | **ID**: R023
+> **Codex port**: `.codex/**` is the active rule/runtime surface; `templates/.claude/**` mirrors compatibility guidance.
+
+## Core Rule
+
+검증은 비용/속도 ladder로 구성한다: **결정론적 검사 → cheap LLM → expensive LLM → human**. 가장 저렴한 tier가 먼저 통과해야 다음 tier로 진행한다. 더 낮은 tier에서 잡을 수 있는 문제를 더 비싼 tier에 보내지 않는다.
+
+## Ladder Tiers
+
+| Tier | 도구 | 비용 | 속도 | 적용 시점 |
+|------|------|------|------|-----------|
+| **1: Deterministic** | hooks, linters, type-check, JSON schema | $0 | <1s | Pre-write, write-time |
+| **2: Cheap LLM** | haiku-based skills (`dev-review`, `action-validator`) | $ | <30s | Per-file review |
+| **3: Expensive LLM** | sonnet/opus skills (`deep-verify`, `adversarial-review`, `multi-model-verification`, `evaluator-optimizer`) | $$$ | 1-5분 | Pre-commit, PR review |
+| **4: Human** | maintainer review | time | hours-days | Final gate, contested decisions |
+
+## Shift-left 원칙
+
+결정론적 단계가 잡을 수 있는 문제는 LLM에 보내지 않는다. LLM 검증은 ambiguous/semantic 문제에 집중한다.
+
+- **좋은 예**: JSON schema 오류 → Tier 1 hook이 차단 → LLM에 미전달
+- **나쁜 예**: 탭/스페이스 혼용 오류 → sonnet으로 전달 → 불필요한 비용 발생
+
+R013 (SHOULD-ecomode)의 "저렴한 검증 우선" 원칙과 정합: ecomode는 출력 토큰을 절약하고, R023은 검증 비용을 절약한다.
+
+## 기존 자산 매핑
+
+| Tier | 자산 | 역할 |
+|------|------|------|
+| **Tier 1** | `.codex/hooks/ (and mirrored templates/.claude/hooks/)` (PreToolUse hooks) | 도구 호출 전 결정론적 차단 |
+| **Tier 1** | `mgr-sauron` (R017 구조 검증) | 에이전트/스킬/가이드 frontmatter 검증 |
+| **Tier 1** | pre-commit configs, linters | 코드 품질 정적 검사 |
+| **Tier 2** | `dev-review` | 파일 단위 haiku 코드 리뷰 |
+| **Tier 2** | `action-validator` | CI/CD 액션 구문 검증 |
+| **Tier 2** | `pre-generation-arch-check` | 생성 전 아키텍처 lite 점검 |
+| **Tier 3** | `deep-verify` | 다단계 품질 검증 (sonnet) |
+| **Tier 3** | `adversarial-review` | 공격자 시각 보안 리뷰 (opus) |
+| **Tier 3** | `multi-model-verification` | 복수 모델 교차 검증 |
+| **Tier 3** | `evaluator-optimizer` | 평가-개선 반복 루프 |
+| **Tier 3** | `worker-reviewer-pipeline` | 구현-리뷰 파이프라인 |
+| **Tier 4** | maintainer manual review | PR approval, final gate |
+
+## R021과의 관계
+
+R021 (MUST-enforcement-policy)과 R023은 **직교**한다. 두 규칙은 서로 다른 차원을 다룬다:
+
+| 규칙 | 질문 | 차원 |
+|------|------|------|
+| **R021** | "어떻게 강제할 것인가?" | Hard block / Soft block / Advisory |
+| **R023** | "어떤 비용으로 검증할 것인가?" | Deterministic / Cheap LLM / Expensive LLM |
+
+같은 도구가 두 규칙에 동시에 속할 수 있다:
+
+- `mgr-sauron`: R021 관점에서 Advisory (PostToolUse hook), R023 관점에서 Tier 1 (구조 검증)
+- `deep-verify`: R021 관점에서 Prompt-based (blocking 없음), R023 관점에서 Tier 3 (expensive LLM)
+- `.codex/hooks/ (and mirrored templates/.claude/hooks/)` stage-blocker: R021 관점에서 Hard Block, R023 관점에서 Tier 1
+
+R021은 위반 시 어떻게 멈출지를, R023은 어떤 순서로 검증할지를 정의한다.
+
+## Self-Check
+
+새 검증 도구 추가 시:
+
+- [ ] 어느 tier에 속하는지 명확한가?
+- [ ] 같은 tier 내 중복 도구는 없는가?
+- [ ] Tier 1에서 잡을 수 있는 문제를 다루는가? (상위 tier 대신 시프트 권고)
+- [ ] Ladder 순서를 문서화했는가? (어떤 검사를 먼저 실행하는지)
+
+## Safety-Signal Rule Authoring — Carve-Out Pre-Check (shift-left)
+
+> Origin: #1353 (인터럽트 룰 #1341의 후속 회고에서 발견된 R001 carve-out 누락) — 인터럽트 룰(R003/R020)을 작성할 때 R001 파괴적-작업 carve-out을 1차 작성에서 빠뜨렸고, Tier 3 적대적 검증이 release-blocking으로 포착해 보정했다. Tier 3가 잡았으나, 같은 결함을 Tier 1(작성 시점 결정론적 점검)로 시프트하면 비용이 낮다.
+
+런타임 안전-신호 동작을 정의하는 룰(인터럽트·취소·halt·중단·emergency-stop 등)을 추가/수정할 때, 작성 단계(Tier 1)에서 다음을 사전 점검한다 — Tier 3 적대적 검증에 의존하기 전에 (이 checklist 같은 메타-룰은 대상 아님):
+
+- [ ] 이 룰이 R001 파괴적·비가역 작업(`git reset --hard`, `clean -fd`, `rm`, 터널/DNS/k8s/인프라 삭제) 컨텍스트에서도 안전한가? (fail-closed carve-out 필요 여부)
+- [ ] "진행/계속(proceed)" 류 지시의 대상이 파괴적 작업의 계속으로 오독될 여지가 없는가?
+- [ ] 안전-신호의 fail-safe 의미(emergency-halt)를 약화시키지 않는가? (stop-first ask-after 우선)
+- [ ] 기존 안전 규칙(R001/R002)과의 우선순위가 명시되어 있는가?
+
+하나라도 불확실하면 **먼저 carve-out을 명시(Tier 1 우선 해결)**하고, 그래도 불확실하면 Tier 3 적대적 검증(`adversarial-review`, `multi-model-verification`)을 통과시킨 뒤 release한다 (ladder 순서 유지). 이는 R023 shift-left 원칙(저렴한 tier 우선)을 룰 작성 자체에 적용한 것이며, R016 룰 작성 워크플로우의 Tier-1 품질 게이트로 동작한다 (R016은 위반 후 룰 업데이트 소유, R023 carve-out은 안전-신호 룰 작성 시 사전 점검 — 직교). Closes #1353.
+
+## Integration
+
+| 규칙 | 상호작용 |
+|------|---------|
+| R009 (Parallel Execution) | Tier 1-2 검사는 독립 파일에 대해 병렬 실행 가능 |
+| R013 (Ecomode) | 컨텍스트 압박 시 Tier 3를 Tier 2로 다운그레이드 고려 |
+| R017 (Sync Verification) | Phase 1-3 검증 단계는 R023 Tier 1-3에 대응 |
+| R021 (Enforcement Policy) | 직교: R021은 blocking 방식, R023은 검증 비용 순서 |
+
+## Workflow Prompt & Verifier Ground-Truth
+
+> Origin: #1266 ③ (High) — a Workflow built the agent prompt as `await agent(prompt) + FACTS`, concatenating the guardrail fact-sheet onto the RETURN VALUE instead of the prompt. The writer never received the facts, hallucinated an in-cluster hostname (`secretary-mcp`), and the adversarial verifier couldn't catch it (the fact was in no source it had).
+
+### Prompt Completion Before Call
+
+Workflow/agent prompts MUST be fully assembled into the prompt string **before** the `agent()` / Agent tool call. Post-call concatenation onto the return value is a footgun — the agent never sees the appended content.
+
+| Anti-pattern | Required |
+|--------------|----------|
+| `const r = await agent(prompt) + FACTS` | `const r = await agent(prompt + FACTS)` — assemble first |
+
+### Workflow Script Sanity Check
+
+Before invoking a Workflow script, deterministically verify:
+
+| Check | Why |
+|-------|-----|
+| No unresolved placeholders (`{phase1_summary}`, `TODO`, `<...>`, `{{ }}`) remain in any agent prompt string | An unfilled placeholder reaches the agent verbatim → garbled task |
+| Template-literal / string concatenation produces the intended prompt (assemble-before-call, see above) | Post-call concatenation (`agent(prompt) + FACTS`) silently drops content |
+| Script parses — balanced braces/quotes, valid JS | A syntax error aborts the entire run after partial work |
+
+#### Common Violation (#1271)
+Session 106 follow-up to #1266 ③: a Workflow authoring error recurred — the guardrail fact-sheet was concatenated onto the agent's RETURN VALUE instead of the prompt string, and a placeholder/assembly slip went uncaught because no pre-run sanity check existed. This check is the deterministic Tier-1 guard that catches such slips before the expensive run.
+
+Origin: #1271 (Workflow authoring error recurrence, session 106).
+
+### Verifier Ground-Truth for Cross-Cutting Facts
+
+Cross-cutting facts not verifiable from the primary source (external URLs, in-cluster DNS/hostnames, infra topology) MUST be supplied to the verifier as explicit ground-truth. Otherwise an adversarial verifier cannot distinguish a hallucinated value from a correct one — a verification blind spot.
+
+Cross-reference: R009 (giant-prompt decomposition), `worker-reviewer-pipeline` skill.

package/templates/.claude/rules/index.yaml

@@ -124,6 +124,14 @@ rules:
     priority: SHOULD
     scope: all
 
+  # Verification Ladder - SHOULD
+  - id: R023
+    name: verification-ladder
+    title: Verification Ladder Rules
+    path: ./SHOULD-verification-ladder.md
+    priority: SHOULD
+    scope: all
+
   # Agent Teams - MUST (Conditional)
   - id: R018
     name: agent-teams

package/templates/.claude/skills/fsd/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: omcustomcodex:fsd
+description: Full Self Driving — autonomous release loop that processes all auto-dev-eligible GitHub issues until none remain, by repeatedly running /pipeline auto-dev then /homework.
+scope: harness
+user-invocable: true
+argument-hint: "[<max-releases>]"
+version: 0.1.0
+effort: high
+---
+
+# /omcustomcodex:fsd — Full Self Driving
+
+Autonomous release loop. Equivalent to running:
+
+```
+/omcustomcodex:goal "모든 이슈가 처리될 때까지" /omcustomcodex:loop "/pipeline auto-dev -> /homework"
+```
+
+This is a **thin alias / orchestrator skill**. It does not implement loop, issue-polling, release, or verification logic — it delegates entirely to existing skills.
+
+## Usage
+
+```
+/omcustomcodex:fsd               # Run until all auto-dev-eligible issues are exhausted
+/omcustomcodex:fsd 3             # Optional: cap at N releases (default: unlimited)
+```
+
+No arguments are required. The default behavior runs until the auto-dev-eligible issue set is empty.
+
+## What It Does
+
+FSD expands into:
+
+1. **`/omcustomcodex:goal` wrapper** — applies disciplined goal-to-execution workflow:
+   - Objective: "모든 이슈가 처리될 때까지"
+   - Delegates planning, gap detection, and R020 completion verification to the `goal` skill
+2. **`/omcustomcodex:loop` recurrence** — self-paced loop, each iteration runs:
+   1. `/pipeline auto-dev` — full release pipeline for the next eligible issue or release unit
+   2. `/homework` — retrospective 찐빠 audit gate
+
+### Loop Convergence
+
+The loop converges naturally when the auto-dev-eligible issue set reaches 0. Issue eligibility follows `/pipeline auto-dev` label selection exactly:
+
+- **Included**: `verify-ready` (preferred), unlabeled auto-dev candidates
+- **Excluded**: `verify-done`, `needs-review`, `decision-needed` labels
+
+Do NOT invent new label logic here — defer to the `pipeline` skill's auto-dev issue selection.
+
+### Iteration Flow (per iteration)
+
+```
+[FSD Iteration N]
+├── /pipeline auto-dev        → one release (PR create → merge → npm publish → milestone close)
+├── /homework                 → extract 찐빠, confirm gate (or --dry-run if requested)
+└── Check: any eligible issues remain?
+    ├── YES → next iteration
+    └── NO  → [FSD Done] converged naturally
+```
+
+## Safety and Discipline
+
+Each iteration operates under full project rules — no relaxation because FSD is autonomous:
+
+| Rule | Applies |
+|------|---------|
+| R001 (safety) | Destructive ops still require explicit approval. Credential guardrails always active. |
+| R009 (parallel) | Independent subtasks within each pipeline iteration run in parallel. |
+| R010 (orchestration) | File modifications follow repo delegation/ownership rules. |
+| R017 (sync verification) | Structural verification passes before any commit. |
+| R020 (completion verification) | Each release verified via `npm view`, `gh release view`, closed issues before `[Done]`. |
+
+`/homework` runs as a **retrospective gate** between iterations — findings go through `omcustomcodex:feedback`'s preview/confirmation gate. The loop does NOT skip homework because it is "automated". If homework requires user confirmation, the loop pauses and waits.
+
+If a release operation triggers the safety classifier, the current iteration stops and surfaces the block before continuing.
+
+## When to Use
+
+| Scenario | Use FSD? |
+|----------|----------|
+| Multiple eligible issues ready to process autonomously | YES |
+| Session where the user wants to "let it run" through the backlog | YES |
+| Verifying the autonomous release loop pattern from session memory | YES |
+| Single targeted issue fix | NO — use `/pipeline auto-dev` directly |
+| Exploratory research / planning only | NO — use `/research` or `/deep-plan` |
+| Only one issue and it needs human judgment | NO — use `/pipeline auto-dev` with manual oversight |
+
+## When NOT to Use
+
+- When issues require stakeholder approval or design decisions before implementation
+- When the issue set includes `decision-needed` or `needs-review` items only
+- When cost sensitivity is high and the issue backlog is large — inspect the eligible set first before running FSD
+
+## Optional Release Cap
+
+Pass a numeric argument to cap at N releases:
+
+```
+/omcustomcodex:fsd 3    # Process at most 3 releases this FSD run
+```
+
+The cap is advisory — the pipeline itself may stop earlier if the eligible set runs out before the cap is reached.
+
+## Session 114 Precedent
+
+This skill was extracted from the upstream manual pattern used in Session 114 (2026-06-09):
+
+```
+/goal "모든 이슈가 처리될 때까지" /loop "/pipeline auto-dev -> /homework"
+```
+
+The Codex port keeps the intent but uses `omcustomcodex:` namespaced goal/loop surfaces to avoid native runtime command collisions.
+
+## Cross-References
+
+| Skill / Rule | Role |
+|--------------|------|
+| `omcustomcodex:goal` | Disciplined goal-to-execution wrapper — objective parse, gap detection, R020 verification |
+| `omcustomcodex:loop` | Session auto-continuation during background work |
+| `pipeline` | `/pipeline auto-dev` — the core release pipeline per iteration |
+| `homework` | Retrospective 찐빠 audit gate per iteration |
+| R001 (safety) | Destructive ops require approval; credential guardrails |
+| R009 (parallel execution) | Parallel subtasks within each pipeline iteration |
+| R010 (orchestrator coordination) | File ownership and delegation discipline |
+| R017 (sync verification) | Structural verification before commit/push |
+| R020 (completion verification) | Actual outcome verified before declaring each release done |
+
+## Design Notes
+
+This skill is intentionally a **thin alias**. It does NOT duplicate issue polling, loop cadence, release steps, retrospective analysis, or completion verification. If the underlying skills evolve, FSD automatically benefits.
+
+## Artifact Output
+
+Artifacts from each iteration follow the constituent skills' conventions:
+
+- Pipeline artifacts: `.codex/outputs/sessions/{YYYY-MM-DD}/pipeline-auto-dev-{HHmmss}.md`
+- Homework artifacts: `.codex/outputs/sessions/{YYYY-MM-DD}/homework-{HHmmss}.md`

package/templates/.claude/skills/help/SKILL.md

@@ -31,9 +31,11 @@ Quick Start:
   status             Show system status
   help <command>     Get help for a specific command
   /omcustomcodex:goal <objective>  Run a goal-to-execution workflow
+  /omcustomcodex:fsd [max]        Run the autonomous full-backlog release loop
 
 Common Commands:
   /omcustomcodex:goal  Keep an objective through planning, execution, and verification
+  /omcustomcodex:fsd   Repeat /pipeline auto-dev + /homework until eligible issues are exhausted
   /update-docs       Sync documentation with project
   /update-external   Update external agents
   /audit-agents      Check agent dependencies

package/templates/.claude/skills/homework/SKILL.md

@@ -161,6 +161,17 @@ Invoke the `omcustomcodex:feedback` skill with the drafted issue content. The us
 
 If `--dry-run` is active, skip this phase and output the draft directly to the conversation instead.
 
+## Cross-Project Import Compatibility
+
+When `homework` is imported into another project, Phase 5 depends on `omcustomcodex:feedback` being available and model-invocable in that project.
+
+| Condition | Behavior |
+|-----------|----------|
+| `omcustomcodex:feedback` model-invocable | Use the normal Phase 4A preview + confirmation gate |
+| feedback skill missing or model invocation disabled | Fall back to manual submission: present the drafted findings to the user, write the dry-run artifact when possible, and ask the user to file/run the feedback workflow themselves |
+
+Do not silently drop a retrospective because the imported feedback skill cannot be invoked.
+
 ### Phase 6: Output Summary
 
 ```

package/templates/.claude/skills/lists/SKILL.md

@@ -28,6 +28,7 @@ System:
   status             Show system status
   help               Show help information
   /omcustomcodex:goal  Run a goal-to-execution workflow
+  /omcustomcodex:fsd   Run the autonomous full-backlog release loop
 
 Manager:
   /create-agent          Create a new agent
@@ -57,6 +58,7 @@ System Commands:
 │ status  │ Show system status and health checks         │
 │ help    │ Show help for commands and agents            │
 │ /omcustomcodex:goal │ Run a goal-to-execution workflow  │
+│ /omcustomcodex:fsd  │ Run full-backlog auto-dev loop    │
 └─────────┴──────────────────────────────────────────────┘
 
 Manager Commands:

package/templates/.claude/skills/status/SKILL.md

@@ -122,7 +122,7 @@ Guides:
   ✓ docker, aws
 
 Commands:
-  system:    lists, status, help, omcustomcodex:goal
+  system:    lists, status, help, omcustomcodex:goal, omcustomcodex:fsd
   manager:   create-agent, update-docs, update-external, audit-agents, fix-refs
   dev:       dev-review, dev-refactor
 

package/templates/guides/claude-code/15-version-compatibility.md

@@ -2,6 +2,30 @@
 
 This guide records Claude Code release-note impact that affects the Claude compatibility template. The Codex-native runtime still uses `.codex/**` and OMX as the primary surface.
 
+## v2.1.170
+
+Published: 2026-06-10.
+
+Source: upstream oh-my-customcode #1352/#1354, Codex port #1504.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| Claude Fable 5 is available through the `fable` alias (`claude-fable-5`) | Useful only for packaged Claude compatibility sessions needing mythos-class reasoning; Codex-native subagents continue to use the OMX model contract and `reasoning_effort`. | Document in R006 as Claude-compatibility metadata. Do not change Codex routing defaults. |
+| VS Code integrated-terminal sessions save transcripts correctly and show them in `--resume` | Improves Claude-template workflows that depend on transcript replay, including imported `homework`/retrospective flows. | Prefer Claude Code v2.1.170+ when testing Claude compatibility transcript-dependent skills. No Codex runtime change. |
+
+## v2.1.169
+
+Published: 2026-06-08.
+
+Source: upstream oh-my-customcode #1329, Codex port #1496.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| `--safe-mode` and `CLAUDE_CODE_SAFE_MODE` start Claude Code with all customizations disabled | Useful for isolating whether a packaged `.claude` template, skill, hook, plugin, or MCP server causes a Claude-compatibility regression. | Document in R006; do not change Codex/OMX runtime loading. |
+| `disableBundledSkills` and `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` hide bundled skills, workflows, and built-in slash commands from the model | Helps when Claude bundled skills duplicate or conflict with project skills. Distinct from advisory `skills:` frontmatter metadata. | Record as Claude platform setting; keep Codex skill roots unchanged. |
+| `claude agents --json` includes blocked and just-dispatched sessions; `--all` includes completed sessions; output includes `id` and `state` | Strengthens Claude-template Agent Teams completion checks. | Prefer `--all` + `state` when diagnosing Claude Agent Teams; Codex/OMX uses native runtime state plus repo evidence. |
+| `/cd` command and reliability fixes for MCP policy/history behavior | Claude operator convenience only. | No Codex runtime change. |
+
 ## v2.1.168
 
 Published: 2026-06-07.

package/templates/guides/openai-codex/01-version-compatibility.md

@@ -2,6 +2,19 @@
 
 This guide records OpenAI Codex release-note impact decisions for oh-my-customcodex. Use it for Codex/OMX runtime compatibility notes; keep Claude-only release notes in `guides/claude-code/15-version-compatibility.md`.
 
+## rust-v0.139.0 / CLI 0.139.0
+
+Source: upstream OpenAI Codex release `rust-v0.139.0`, Codex-port issue #1498.
+
+| Change | Impact on oh-my-customcodex | Action |
+| --- | --- | --- |
+| Code mode can call standalone web search directly, including nested JavaScript tool calls, and receive plaintext results | Improves Codex runtime research ergonomics but does not change packaged skill/tool routing. | Keep repository research guidance source-backed; no package dependency change. |
+| Tool and connector schemas preserve `oneOf`/`allOf`; large schemas keep more shallow structure during compaction | Reduces MCP/app connector schema loss for richer tools. | No template migration; continue to prefer connector schemas as runtime ground truth. |
+| `codex doctor` includes editor and pager environment details while redacting raw values in JSON output | Aligns with metadata-only diagnostics and secret-redaction rules. | Document compatibility; keep `omcustomcodex doctor` separate. |
+| Plugin marketplace automation exposes marketplace source in `list --json` and returns cached catalogs before background refresh | Useful for future plugin inventory automation. | Prefer JSON when automating plugin inventory; no current CLI behavior change. |
+| `codex resume --last "..."` and `codex fork --last "..."` treat trailing text as the initial prompt | Reduces operator surprise for resume/fork workflows. | No package change. |
+| MCP startup warnings are scoped to the owning thread, image edits use exact referenced paths, URLs with `~` linkify correctly, thread resets preserve cloud requirements, and sandbox execution preserves approved escalation/proxy-only networking more consistently | Runtime stability and evidence quality improvements. | No package change beyond this compatibility record. |
+
 ## rust-v0.138.0 / CLI 0.138.0
 
 Source: upstream OpenAI Codex release `rust-v0.138.0`, Codex-port issue #1481.

package/templates/manifest.json

@@ -1,17 +1,17 @@
 {
-  "version": "0.5.20",
+  "version": "0.5.22",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",
     "protectedPathBypassVersion": "2.1.126"
   },
-  "lastUpdated": "2026-06-06T00:00:00.000Z",
+  "lastUpdated": "2026-06-11T00:00:00.000Z",
   "components": [
     {
       "name": "rules",
       "path": ".codex/rules",
       "description": "Agent behavior rules and guidelines",
-      "files": 22
+      "files": 23
     },
     {
       "name": "agents",
@@ -23,7 +23,7 @@
       "name": "skills",
       "path": ".agents/skills",
       "description": "Reusable skill modules (project-scoped repo skills)",
-      "files": 121
+      "files": 122
     },
     {
       "name": "guides",

package/templates/workflows/auto-dev.yaml

@@ -140,6 +140,10 @@ steps:
       6. Halt if current failures exceed baseline; otherwise report pass/fail counts and delta.
       7. Run `bun run build` when available.
 
+      Documentation/template validation:
+      - For local or CI docs validation, run `bun run .github/scripts/validate-docs.ts --programmatic-only` (or the repo's equivalent validate-docs command with `--programmatic-only`) before assuming a validation failure is an authentication failure.
+      - Treat interactive/auth-dependent validate-docs output as inconclusive until the programmatic-only path has been tried.
+
       Halt on lint errors, typecheck errors, new test failures, build failure, or lockfile drift.
     description: Auto-detected build + test verification with mandatory bun test baseline delta guard
 
@@ -155,6 +159,13 @@ steps:
 
       Required version preflight for npm package releases:
       - Determine NEW_VERSION before creating a release branch, PR, or tag.
+      - Version decision (semver) — PATCH-PREFERRED policy from v1.0.0 onward:
+        * No existing tags → v0.1.0.
+        * Previous tag exists → default to patch. When in doubt, patch; do not reflexively bump minor for rule/doc/skill/config/wiki/workflow edits.
+        * patch (DEFAULT): bugfixes, hardening, rule/doc/skill/config/wiki/workflow changes, compatibility notes, and release-process guardrails.
+        * minor: only a genuinely new user-facing capability, such as a new skill/agent/command adding visible surface, not a refinement of an existing one.
+        * major: breaking changes to user-facing contracts (CLI flags, public skill/command names, public API) or a deliberate milestone declaration such as v1.0.0.
+        * If a previous tag is ahead of the source version, use the next available skip-version.
       - Update `package.json` and `templates/manifest.json` to NEW_VERSION in the same commit.
       - Promote `CHANGELOG.md` before the release PR/tag: move non-empty `## [Unreleased]` entries into `## [NEW_VERSION] - YYYY-MM-DD`, then re-create an empty `## [Unreleased]` section above it.
       - If `CHANGELOG.md` has no user/package-visible entry for NEW_VERSION, add a concise release summary before continuing instead of relying on GitHub auto-generated release notes.