claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/codex/INSTALL.md

@@ -0,0 +1,342 @@
+# Codex CLI — Installation Guide
+
+## Standalone install and update
+
+From the **target project's Git directory**, run the installer from your Superkit
+checkout (Node.js 18+ and Git required):
+
+```bash
+cd /path/to/your-project
+bash /path/to/claude-code-superkit/setup.sh --codex-only
+```
+
+This noninteractive route installs only Codex assets. It does not require or call
+Claude, install Claude plugins, write `.claude` or `CLAUDE.md`, or scaffold Claude
+documentation. It works from a subdirectory and targets the Git repository root.
+The Codex executable is optional for file setup; install it separately to use the
+skills. Existing `.claude` files do not influence Codex install/update decisions.
+
+The installer supplies 82 skills at `.codex/skills/<name>/SKILL.md` and relative
+links at `.agents/skills/<name>` for current Codex discovery. The retained storage
+path keeps older installations and references compatible. Codex documents
+repository discovery under `.agents/skills` and supports linked skill folders:
+[official skill documentation](https://learn.chatgpt.com/docs/build-skills).
+Existing discovery entries are preserved and reported as `DISCOVERY CONFLICT`;
+you choose which skill to expose. The installer never replaces those entries or
+follows an external link to update it. Creating directory symlinks requires OS
+support/permission (on Windows, typically Developer Mode); failure is reported,
+not silently treated as a complete installation.
+
+It creates root `AGENTS.md`, `.codex/config.toml`, and
+`.codex/rules/default.rules` only when absent. Existing copies are **always
+preserved**, including prior stock templates. Review new template defaults and
+merge any desired changes yourself. Default coordinator configuration is
+**gpt-6-astra / high**, with **gpt-5.6-sol / medium** subagent fallback;
+configuration is not proof of model availability or behavioral quality.
+
+It also installs two native hook handlers in `.codex/hooks/superkit.mjs` and
+the merge template `.codex/superkit-hooks.json`. A new `.codex/hooks.json` is
+created only when absent, the project config is absent or exactly the shipped
+config, and neither managed hook asset conflicts. Existing hook definitions and
+arbitrary config are preserved; review and merge the template manually when
+needed. The installer never grants project trust or hook trust. Review both
+the definition and script, then use `/hooks` in a supporting Codex runtime.
+See [native hook setup and limits](#native-hooks-and-trust).
+
+### Re-run the same command to update
+
+Refresh your Superkit checkout to the desired reviewed version, then run
+`--codex-only` again. Updates are explicit; no scheduler or Claude SessionStart
+hook is installed for Codex.
+
+| Target state | Behavior |
+| --- | --- |
+| No `.codex` | Fresh install; preserve any existing root instructions/discovery entries. |
+| Existing, unrecognized skills | Merge: add missing skills, preserve/report differing existing skills. |
+| Recorded Superkit hashes | Upgrade skills and hook assets only when still matching their recorded installed hash. |
+| Stock v1.5.2 installation without a manifest | Recognize pristine skills using the bundled SHA-256 baseline, then upgrade safely. |
+| Custom skill or hook asset differs from its baseline and incoming content | `CONFLICT`: retain local bytes and report the upstream source for manual comparison. |
+| Existing managed-path file exactly matches incoming content | Adopt it as managed without rewriting it. |
+
+The installer maintains `.codex/.superkit-manifest.json` (schema 1, installed
+`skills` hashes and an optional `assets` map for the hook script/template).
+Older schema-1 manifests without `assets` remain valid. Active `hooks.json` is
+preserved configuration, not a managed update asset. Preserve the manifest with
+the installed files. The legacy baseline
+in `packages/codex/legacy-baseline.json` is pinned to v1.5.2 commit
+`cbb0565f4d4868fe77f4bd7e8fdd46dada3e52ab`; it requires no network access.
+Other unknown versions are merged conservatively. Missing shipped skills are
+recreated; removed upstream roles and unrelated/support files are not deleted.
+To disable a skill, use Codex's skill configuration rather than deleting its file.
+
+Before replacing pristine skills or hook assets, the installer writes old bytes and the
+previous manifest (if present) into a new, unique directory under
+`.codex/.superkit-backups/`, printing its absolute path. Existing backups are never
+deleted or reused. For rollback, stop installers, inspect the printed backup, and
+restore selected `skills/<name>/SKILL.md`, `hooks/superkit.mjs` and/or
+`superkit-hooks.json` files to their corresponding paths under `.codex/`; restore
+the backed-up manifest as well for a full rollback of that update. New files from
+that run remain until you explicitly remove them. A legacy first upgrade has no
+old manifest; restored legacy bytes will be preserved as conflicts on subsequent
+runs, so compare and resolve them manually.
+
+A conflicting file is a successful **preserving** install, not a fully applied
+upstream update. Read the summary. Corrupt manifests, incomplete packages,
+symbolic links in managed write paths, and non-regular files stop installation
+with an error. Known discovery links are the intentional exception; discovery
+parents must be real directories. `.codex/.superkit-install.lock` prevents
+concurrent installer runs. After an interrupted run, verify no installer is
+active before removing a stale lock and rerunning. Individual replacements are
+atomic, but the whole install is not a transaction; backups cover replacements
+and a rerun preserves unrecognized partial-update bytes. Do not edit target files
+concurrently with installation. This is not a hostile-filesystem sandbox.
+
+### Existing combined installer
+
+`--codex` keeps its additive meaning: Claude + Codex. For example:
+
+```bash
+bash /path/to/claude-code-superkit/setup.sh --defaults --codex
+```
+
+The Codex portion uses the same independent update policy even when the Claude
+portion is fresh, merged, or overwritten. `--codex-only` rejects `--codex`,
+`--stacks`, `--extras`, `--profile`, and `--plugins` together. `--defaults`,
+`--no-docs`, and `--no-superpowers` are accepted but unnecessary in standalone mode.
+
+### v1.5.3 release artifact
+
+The v1.5.3 package archive includes both installers, the Claude layer and optional
+GAN sources; `--codex-only` selects only Codex assets for your project. Use the
+package archive attached to the [v1.5.3 GitHub release](https://github.com/RaNDoM6913/claude-code-superkit/releases/tag/v1.5.3),
+or create the same package format from a reviewed v1.5.3 checkout:
+
+```bash
+npm pack --ignore-scripts --pack-destination /path/to/artifacts
+```
+
+Extract the resulting archive to a separate directory, then run from your target
+project:
+
+```bash
+node /path/to/extracted/package/bin/cli.js --codex-only
+```
+
+The archive includes the installer, skill sources, hook script/template, and legacy baseline.
+The archive version is 1.5.3. Re-run the extracted installer to update an existing
+project under the same preservation and backup policy. GitHub release archives
+and the tagged checkout are usable independently of npm registry availability.
+Check `npm view claude-code-superkit@1.5.3 version`; when it returns `1.5.3`, the
+equivalent command from your target project is
+`npx claude-code-superkit@1.5.3 --codex-only`.
+
+### Use and manual installations
+
+Start Codex in the target project, open `/skills` or type `$` and select a role,
+for example `$code-reviewer`. Customize `AGENTS.md` with actual project facts.
+If new skills do not appear, restart Codex and check reported discovery conflicts.
+Discovery proves loading, not successful execution of a workflow or model quality.
+
+For selective/manual setup, place chosen skill folders (or links to them) under
+project `.agents/skills/`; copy the templates only when absent and merge existing
+configurations manually. Manual linked-source skills follow their source checkout
+and do not receive installer-managed backups. Global installations are manual;
+this installer never writes to `~/.codex` or `~/.agents`.
+
+## What Gets Installed
+
+Automated installation includes all 82 skills below. For manual selection only,
+create `.agents/skills/` before copying and preserve any existing same-name folders.
+
+### 9 Command Skills (user-invocable)
+
+| Skill | Description |
+|-------|-------------|
+| `dev-orchestrator` | 16-phase development cycle: read-docs, understand, architect, pseudocode, plan, contract, validate, implement, evaluate, verify, test, verify-goals, review, critic, document, report |
+| `review-orchestrator` | Detect changes, gather git context, dispatch reviewer agents in parallel, collect and deduplicate findings |
+| `audit-orchestrator` | Parallel audit across frontend, backend, infra, security |
+| `test-runner` | Auto-detect project test runner and execute tests |
+| `lint-runner` | Auto-detect linters, run with optional --fix mode |
+| `commit-helper` | Conventional commit with secret detection |
+| `new-migration` | Discover the migration tool/dialect and scaffold its native format without applying it |
+| `migrate` | Inspect status by default; apply or roll back an explicitly authorized, bounded set |
+| `benchmark` | Run available Go benchmarks; compare an isolated baseline with installed tools |
+
+### 36 Agent Skills (available roles)
+
+These include converted core/extras roles and native GPT roles with Astra-authored instructions. `native-skills.txt` lists protected native roles, adapted workflows and support sources; the converter preserves them and rejects missing declared native assets before writing. The [roadmap](../../docs/superpowers/plans/2026-10-09-gpt-agent-roadmap-1.5.3.md) tracks accepted role packets separately from target-model behavioral acceptance. Source ownership is not proof of model quality. Use depends on the task, user authorization, and available runtime tools; automatic dispatch applies only where an existing caller selects the role. `behavioral-nudge-engine` is available for product nudge-design tasks and has no automatic Codex orchestrator caller. **v1.4.0 added 4 specialist roles:**
+
+- `minimal-change-engineer` — surgical implementation, refuses scope creep
+- `reality-checker` — checks readiness claims against applicable evidence and reports external blockers
+- `codebase-onboarding-engineer` — task-focused repository brief with verified facts and explicit unknowns
+- `behavioral-nudge-engine` — retention psychology, habit loops
+
+| Skill | Category |
+|-------|----------|
+| `code-reviewer` | Quality — generic code review |
+| `comment-rot-analyzer` | Quality |
+| `security-scanner` | Security — OWASP top-10 + 18 generic checks |
+| `silent-failure-hunter` | Quality |
+| `audit-frontend` | Audit — 12 frontend checks against assigned product, data and toolchain contracts; evidence gaps explicit |
+| `audit-backend` | Audit — 12 backend domains against assigned API, data-access and operational contracts; evidence gaps explicit |
+| `audit-infra` | Audit — infrastructure security (12 checks) |
+| `migration-reviewer` | Quality — SQL migration review |
+| `test-generator` | Productivity — generate tests |
+| `e2e-test-generator` | Productivity — Playwright/Cypress tests |
+| `health-checker` | DevOps — compilation checks |
+| `pre-deploy-validator` | DevOps — pre-deploy checklist (9 points) |
+| `dependency-checker` | DevOps — dependency audit |
+| `debug-observer` | Observability — debug analysis |
+| `docs-reviewer` | Quality — documentation freshness, accuracy, coverage |
+| `api-contract-sync` | Quality — API spec ↔ routes sync |
+| `scaffold-endpoint` | Productivity — new endpoint scaffolding |
+| `ui-reviewer` | Quality — UI/UX design system review |
+| `bot-reviewer` | Quality — bot code review (Telegram/Discord/Slack) |
+| `design-system-reviewer` | Quality — design system compliance |
+| `database-reviewer` | Quality — PostgreSQL specialist |
+| `architect` | Quality — system design advisor |
+| `plan-checker` | Quality — requirement coverage, repository facts, dependencies, authority and feasible verification; PASS / REVISE / BLOCK |
+| `goal-verifier` | Quality — 4-level goal substantiation, 3-state verdict (PASS / NEEDS-ATTENTION / NEEDS-REMEDIATION) |
+| `evaluator` | Quality — calibrated QA scoring against Sprint Contract |
+| `project-architecture` | Knowledge — project architecture reference |
+| `ai-slop-cleaner` | Quality — detect and fix AI-generated code patterns |
+| `critic` | Quality — multi-perspective final quality gate |
+| `visual-reviewer` | Quality — visual/design-system review with separate source, rendered and interaction evidence; scoring only with an approved rubric |
+| `tree-generator` | Productivity — generate project tree files |
+| `writing-agents` | Knowledge — how to write agents |
+| `writing-commands` | Knowledge — how to write command orchestrators |
+
+### Frontend UI Skills (included; manual selection for 2D UI projects)
+
+- `frontend-ui-reviewer` — umbrella reviewer
+- `frontend-ui-typography-reviewer`, `frontend-ui-color-reviewer`,
+  `frontend-ui-motion-reviewer`, `frontend-ui-interaction-reviewer`,
+  `frontend-ui-design-critic` — five specialists
+- `impeccable-craft` — opt-in craft skill
+
+### Frontend 3D Skills (included; manual selection for 3D projects)
+
+- Reviewers: `presentation-reviewer`, `r3f-scene-reviewer`,
+  `ui-design-reviewer`, `frontend-perf-reviewer`
+- Knowledge: `threejs-color-management`, `r3f-scroll-driven-3d`, `gltf-debugging`,
+  `html-to-3d-texture`, `product-3d-lighting`, `output-enforcement`
+
+### Stack-Specific Reviewers (included; manual selection per language)
+
+- Go reviewers: `go-reviewer`, `go-error-reviewer`, `go-concurrency-reviewer`,
+  `go-performance-reviewer`, `go-modernizer`, `go-observability-reviewer`
+- Go knowledge: `go-samber-do`, `go-samber-oops`, `go-samber-lo`,
+  `go-grpc-patterns`, `go-benchmark`
+- Other languages: `ts-reviewer`, `py-reviewer`, `rs-reviewer`
+
+For selective manual setup, each source folder is under `packages/codex/skills/`.
+Confirm its destination under `.agents/skills/` is absent before copying or linking.
+If it exists, compare and merge manually; copying over it bypasses all installer
+preservation and backup checks. Prefer the automated route for managed updates.
+
+### Total: 82 skills
+
+- 9 command skills (user-invocable, including benchmark)
+- 36 agent + knowledge skills (task-specific use or existing caller dispatch) — incl. v1.4.0: minimal-change-engineer, reality-checker, codebase-onboarding-engineer, behavioral-nudge-engine
+- 10 frontend 3D skills (optional, for R3F/Three.js/GSAP projects)
+- 7 frontend UI skills (optional, for 2D UI / landing-page / dashboard projects)
+- 9 stack-specific reviewer skills (optional, per language)
+- 5 Go knowledge skills (optional, samber-do/oops/lo, grpc-patterns, benchmark-methodology)
+- 6 TGApp / production skills (telegram-bot-builder, nextjs-supabase-auth, drizzle-orm-expert, ru-text, postgresql-optimization, redis-patterns)
+
+Plus 1 Codex approval rules file (`packages/codex/rules/default.rules`), 2 hook handlers in 1 script, and 3 GAN agents (separate optional package, requires Playwright).
+
+## Model Configuration
+
+The default `config.toml` separates coordinator and subagent models:
+
+```toml
+model = "gpt-6-astra"
+model_reasoning_effort = "high"
+web_search = "live"
+
+[features]
+multi_agent = true
+
+[agents]
+default_subagent_model = "gpt-5.6-sol"
+default_subagent_reasoning_effort = "medium"
+```
+
+Skills are instructions used by the agent that loads them; skill frontmatter does not select the execution model. The agent defaults apply when a dispatch omits model or effort. Explicit task routing should select the intended model and effort, with substantive Sol review at `high` and critical decisions accepted by Astra. The supported effort levels and model availability depend on the installed runtime and account.
+
+These settings were checked against Codex CLI `0.162.0-alpha.17.2` and the [official configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference). They declare routing; they do not prove a live task ran on that model. Model behavioral acceptance remains pending. The owner-required Astra authorship rule for Superkit contributors is documented in [WORKING_AGREEMENT.md](../../docs/WORKING_AGREEMENT.md).
+
+## Native hooks and trust
+
+Codex supports lifecycle hooks in `hooks.json` beside active config layers;
+project-local hooks also require project trust. See the [official hooks and
+trust documentation](https://learn.chatgpt.com/docs/hooks) and
+[configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
+Superkit ships this bounded mapping:
+
+| Handler | Check | Limit |
+| --- | --- | --- |
+| `PreToolUse` (`Bash`) | Rejects recognized static destructive Git commands | Never returns permission allow; opaque shell syntax is unassessed. It is not a complete shell parser/security boundary. |
+| `Stop` | Filter-free repositories: read-only tracked/staged `git diff --check`; at most one continuation | Any configured clean/process filter skips both diffs with UNVERIFIED. Does not prove tests/builds passed or check untracked file behavior. |
+
+Git diff checks can execute clean/process conversion programs. Before either
+diff, Stop enumerates config keys only and conservatively skips both checks when
+any `filter.*.clean` or `filter.*.process` is configured, including unused drivers
+and global Git LFS configuration. No filter values are captured or Git config
+changed. This availability limit remains UNVERIFIED, never a whitespace pass;
+run the applicable verification explicitly under its own task authority.
+
+The handlers run no project scripts, read no transcripts and contact no external
+services. Wiring resolves the Git root through a POSIX shell; Windows and cloud
+runtime execution are unqualified. Keep task authority, approvals and real
+verification gates in force even when a hook returns no block.
+
+After installation, inspect `.codex/hooks.json` or manually merge
+`.codex/superkit-hooks.json` into your existing hook configuration. Other active
+sources can also contribute hooks; avoid duplicate registrations. Review the
+referenced `.codex/hooks/superkit.mjs`, trust the project when appropriate and
+use `/hooks` to review the exact definition. The installer writes no trust
+settings and never bypasses trust. An existing active hook definition is preserved
+on updates. Definition-hash trust does not fully attest the referenced script:
+review managed script changes separately, including backup/conflict reports.
+
+A copied definition is not proof of trust, handler execution or native event
+firing. Check each separately in the intended runtime. Direct script fixtures
+qualify handler behavior only; file installation/discovery checks do not establish
+native firing, consumer workflow execution or model quality.
+
+For this release, actual Codex CLI `0.162.0-alpha.17.2` in a disposable POSIX/macOS
+fixture observed native PreToolUse blocking a hard reset and Stop progressing from
+blocked to completed, followed by a completed turn. Normal folder trust and
+individual definition review were used. The [activation record](../../docs/superpowers/migrations/astra-native/evidence/GPT-codex-native-activation-candidate-2026-10-15.md)
+preserves the partial first attempt and completed successor. This evidence does
+not activate hooks in your project or qualify Windows/cloud, every workflow,
+arbitrary shell syntax or model quality.
+
+### Claude behaviors without a shipped Codex mapping
+
+| Feature | Claude Code | Codex route |
+| --- | --- | --- |
+| Session continuity | SessionStart restore / pre-compact save | Not mapped; maintain authorized project notes. |
+| Full Stop verification | Compilation/documentation checks | Not mapped; run applicable test/lint/docs gates. |
+| Format/typecheck-on-edit | Language-specific PostToolUse checks | Not mapped; use editor checks or authorized lint-runner fixes. |
+| Doc-check-on-commit | Documentation commit gate | Not mapped; follow AGENTS.md and docs-reviewer. |
+| Migration validation | Migration naming/safety hooks | Not mapped; use applicable migration skills and task authority. |
+| Bundle import check | Dependency warning | Not mapped; use dependency-checker. |
+| Hook profiles | fast/standard/strict | Not mapped; review the two native handler definitions directly. |
+
+## Verification
+
+Inspect `.codex/skills/`, `.agents/skills/`, root `AGENTS.md` and the installed
+config/rules and managed hook script/template. In Codex, use `/skills` or `$`
+to verify discovery and `/hooks` to inspect hook review/trust status. The installer
+reports conflicts explicitly; a successful run does not imply every upstream
+change replaced a local customization.
+
+## Updating
+
+Use the [safe re-run procedure](#re-run-the-same-command-to-update) above.
+Do not recursively copy over installed skills to update them: that bypasses
+customization checks and backups. For manual linked installations, review the
+source-checkout changes before refreshing it.

package/packages/codex/config.toml

@@ -0,0 +1,22 @@
+# claude-code-superkit — Codex CLI configuration
+# Place in .codex/config.toml (project) or ~/.codex/config.toml (global)
+
+model = "gpt-6-astra"
+model_reasoning_effort = "high"
+web_search = "live"
+
+[features]
+multi_agent = true
+
+[agents]
+default_subagent_model = "gpt-5.6-sol"
+default_subagent_reasoning_effort = "medium"
+
+# MCP servers (uncomment as needed)
+# [mcp_servers.playwright]
+# command = "npx"
+# args = ["@playwright/mcp@latest"]
+
+# [mcp_servers.context7]
+# command = "npx"
+# args = ["-y", "@context7/mcp@latest"]

package/packages/codex/hooks/superkit.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+// Native Codex command hooks. No transcript reads, model calls, project scripts or writes.
+import { spawnSync } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+
+const mode = process.argv[2];
+const deny = reason => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } });
+const unverified = () => ({ systemMessage: 'Superkit diff hygiene UNVERIFIED: invalid input, unavailable Git, non-repository cwd, or bounded Git check failure. Run applicable verification explicitly; do not claim a pass.' });
+
+// Deliberately a recognizer for explicit shell words, not a shell interpreter.
+// Expansions, heredocs and nested interpreters are not assessed. Native permission
+// rules/sandbox/user authority still apply; this hook never emits "allow".
+function shellWords(command) {
+  const commands = [];
+  let words = [], word = '', quote = '', started = false, opaque = false;
+  const finishWord = () => { if (started) words.push(word); word = ''; started = false; };
+  const finishCommand = () => { finishWord(); if (words.length) commands.push(words); words = []; };
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote === "'") {
+      if (ch === quote) quote = ''; else word += ch;
+      continue;
+    }
+    if (ch === '\\' && quote !== "'") {
+      if (i + 1 >= command.length) { opaque = true; break; }
+      const next = command[++i];
+      if (next !== '\n') { word += next; started = true; }
+      continue;
+    }
+    if (ch === '$' || ch === '`') opaque = true;
+    if (quote === '"') {
+      if (ch === quote) quote = ''; else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; started = true; continue; }
+    if (ch === '#' && !started) {
+      while (i < command.length && command[i] !== '\n') i++;
+      finishCommand(); continue;
+    }
+    if (ch === '<' && command[i + 1] === '<') { opaque = true; break; }
+    if ('<>()[]{}*?~'.includes(ch)) opaque = true;
+    if (';&|\n'.includes(ch)) { finishCommand(); continue; }
+    if (/\s/.test(ch)) { finishWord(); continue; }
+    word += ch; started = true;
+  }
+  if (quote) opaque = true;
+  finishCommand();
+  return { commands, opaque };
+}
+
+function commandIndex(words) {
+  let i = 0;
+  const assignments = () => { while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i] || '')) i++; };
+  assignments();
+  if (words[i] === 'env') {
+    i++;
+    while (['-i', '--ignore-environment', '--'].includes(words[i])) i++;
+    assignments();
+  }
+  if (words[i] === 'command') { i++; if (words[i] === '--') i++; }
+  return i;
+}
+
+function gitArgs(words) {
+  let i = commandIndex(words);
+  if (!/(^|\/)git$/.test(words[i] || '')) return null;
+  i++;
+  while (words[i]?.startsWith('-')) {
+    const option = words[i++];
+    if (['-C', '-c', '--git-dir', '--work-tree', '--namespace'].includes(option)) { i++; continue; }
+    if (/^(?:-C.|-c.|--(?:git-dir|work-tree|namespace)=)/.test(option)) continue;
+    if (['--no-pager', '--paginate', '--bare', '--literal-pathspecs', '--no-optional-locks'].includes(option)) continue;
+    return { opaque: true };
+  }
+  return { operation: words[i], args: words.slice(i + 1) };
+}
+
+// Value-taking options must be consumed before inspecting flags. In a short
+// cluster, the remainder after such an option is its value (e.g. -amtext).
+// This intentionally covers the direct Git forms below, not Git aliases or
+// arbitrary wrappers/option abbreviations.
+function gitOptions(operation, args) {
+  const valueOptions = {
+    commit: ['mFctC', '--message', '--file', '--reuse-message', '--reedit-message', '--template', '--author', '--date', '--fixup', '--squash', '--cleanup', '--trailer', '--pathspec-from-file'],
+    push: ['o', '--push-option', '--repo', '--receive-pack', '--exec'],
+    merge: ['mFsX', '--message', '--file', '--strategy', '--strategy-option', '--into-name'],
+    rebase: ['sXx', '--onto', '--exec', '--strategy', '--strategy-option'],
+    clean: ['e', '--exclude'],
+    branch: ['', '--format', '--sort', '--points-at'],
+    reset: ['', '--pathspec-from-file'],
+    checkout: ['bB', '--orphan', '--conflict', '--pathspec-from-file'],
+    switch: ['cC', '--create', '--force-create', '--orphan', '--conflict'],
+    restore: ['s', '--source', '--conflict', '--pathspec-from-file']
+  }[operation] || [''];
+  const flags = new Set(), operands = [];
+  let separator = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (separator) { operands.push(arg); continue; }
+    if (arg === '--') { separator = true; continue; }
+    if (arg.startsWith('--')) {
+      const name = arg.split('=', 1)[0];
+      flags.add(name);
+      if (!arg.includes('=') && valueOptions.includes(name)) i++;
+    } else if (/^-[^-]/.test(arg)) {
+      for (let j = 1; j < arg.length; j++) {
+        flags.add(`-${arg[j]}`);
+        // Optional short values are attached only; e.g. -Skey must not turn
+        // letters in a signing key into commit flags, or consume the next flag.
+        if (operation === 'commit' && 'Su'.includes(arg[j])) break;
+        if (valueOptions[0].includes(arg[j])) {
+          if (j === arg.length - 1) i++;
+          break;
+        }
+      }
+    } else operands.push(arg);
+  }
+  return { flags, operands, separator };
+}
+
+function destructive(operation, args) {
+  const { flags, operands, separator } = gitOptions(operation, args);
+  const short = flag => flags.has(`-${flag}`);
+  const has = flag => flags.has(flag);
+  if (operation === 'commit' && (has('--no-verify') || short('n'))) return 'commit verification bypass';
+  if (['push', 'merge', 'rebase'].includes(operation) && has('--no-verify')) return 'verification bypass';
+  if (operation === 'push' && (short('f') || has('--force') || operands.some(a => a.startsWith('+')))) return 'force push';
+  if (operation === 'reset' && has('--hard')) return 'hard reset';
+  if (operation === 'clean' && !has('--dry-run') && !short('n') && (has('--force') || short('f'))) return 'forced clean';
+  if (operation === 'branch' && (short('D') || ((has('--delete') || short('d')) && (has('--force') || short('f'))))) return 'forced branch deletion';
+  if (operation === 'checkout' && (separator || operands.includes('.') || has('--force') || short('f') || short('B'))) return 'checkout discarding work';
+  if (operation === 'switch' && (has('--discard-changes') || has('--force') || has('--force-create') || short('f') || short('C'))) return 'switch discarding work';
+  if (operation === 'restore' && (!(has('--staged') || short('S')) || has('--worktree') || short('W'))) return 'restore overwriting working files';
+  return null;
+}
+
+function preTool(input) {
+  if (input?.hook_event_name !== 'PreToolUse' || typeof input.tool_name !== 'string') return deny('Superkit Git guard could not validate the hook input. Check the installed hook integration.');
+  if (input.tool_name !== 'Bash') return {};
+  const command = input.tool_input?.command;
+  if (typeof command !== 'string' || !command.trim()) return deny('Superkit Git guard received no valid shell command.');
+  const parsed = shellWords(command);
+  let opaque = parsed.opaque;
+  for (const words of parsed.commands) {
+    const executable = words[commandIndex(words)]?.split('/').pop();
+    if (['sh', 'bash', 'zsh', 'eval', 'source', '.'].includes(executable)) opaque = true;
+    const git = gitArgs(words);
+    if (!git) continue;
+    if (git.opaque) { opaque = true; continue; }
+    const reason = destructive(git.operation, git.args);
+    if (reason) return deny(`Superkit blocked explicit ${reason}. Preserve work and use a non-destructive operation; do not bypass this hook. User authorization and native permissions remain required.`);
+  }
+  return opaque ? { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: 'Superkit Git guard: dynamic or unsupported shell syntax was not assessed. This is not permission to execute it; inspect the exact operation and apply native permissions and user authority.' } } : {};
+}
+
+function git(cwd, args) {
+  // Event cwd is the repository authority. Inherited Git location/index overrides
+  // must not silently redirect hygiene checks to a different worktree or index.
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' };
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_PREFIX']) delete env[key];
+  return spawnSync('git', ['--no-pager', '-c', 'core.fsmonitor=false', ...args], {
+    cwd, encoding: 'utf8', timeout: 3000, maxBuffer: 1024 * 1024, windowsHide: true,
+    env
+  });
+}
+
+function stop(input) {
+  if (input?.hook_event_name !== 'Stop' || typeof input.cwd !== 'string' || !isAbsolute(input.cwd)) return unverified();
+  const root = git(input.cwd, ['rev-parse', '--show-toplevel']);
+  if (root.error || root.status !== 0 || !root.stdout.trim()) return unverified();
+  // --no-ext-diff/--no-textconv do not disable clean/process conversions, which
+  // Git may run while comparing a working file. Enumerate names only, without
+  // reading handler values into this process or executing any diff first.
+  const filters = git(root.stdout.trim(), ['config', '--includes', '--name-only', '--get-regexp', '^filter\\..*\\.(clean|process)$']);
+  if (filters.error || ![0, 1].includes(filters.status)) return unverified();
+  if (filters.status === 0) return {
+    systemMessage: 'Superkit diff hygiene UNVERIFIED: Git clean/process conversion filters are configured. Skipped diff checks to avoid executing configured conversion programs. This also applies to unused configured filters; run applicable verification explicitly without claiming this hook passed.'
+  };
+  const results = [
+    git(root.stdout.trim(), ['diff', '--no-ext-diff', '--no-textconv', '--check']),
+    git(root.stdout.trim(), ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--check'])
+  ];
+  if (results.some(r => r.error || ![0, 2].includes(r.status))) return unverified();
+  if (results.every(r => r.status === 0)) return {};
+  const reason = 'Superkit Git diff hygiene found whitespace errors or conflict markers in tracked staged/unstaged changes. Inspect git diff --check and git diff --cached --check. Fix only changes within authorized scope; preserve/report pre-existing or unrelated errors. This check does not verify tests, builds, untracked files or behavior.';
+  return input.stop_hook_active ? { systemMessage: `${reason} No further automatic continuation requested.` } : { decision: 'block', reason };
+}
+
+try {
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of process.stdin) {
+    length += chunk.length;
+    if (length > 1024 * 1024) throw new Error('Oversized input');
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (mode !== 'pre-tool' && mode !== 'stop') throw new Error('Unknown hook mode');
+  console.log(JSON.stringify(mode === 'pre-tool' ? preTool(input) : stop(input)));
+} catch {
+  // Do not echo payloads, commands, messages, transcripts or diff contents.
+  console.log(JSON.stringify(mode === 'pre-tool' ? deny('Superkit Git guard input/check failed. Review the hook installation before retrying.') : unverified()));
+}

package/packages/codex/hooks.json

@@ -0,0 +1,30 @@
+{
+  "description": "Superkit Codex guards: explicit destructive Git commands and tracked diff hygiene. Review/trust through /hooks; never auto-trusted by the installer.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/superkit.mjs\" pre-tool",
+            "timeout": 10,
+            "statusMessage": "Superkit Git safety check"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/superkit.mjs\" stop",
+            "timeout": 15,
+            "statusMessage": "Superkit tracked diff hygiene"
+          }
+        ]
+      }
+    ]
+  }
+}