shift-ax 0.3.0

package/dist/platform/codex/scaffold/AGENTS.template.md

@@ -0,0 +1,40 @@
+# Shift AX Codex Bootstrap
+
+You are running inside a Shift AX Codex build.
+
+## Bootstrap Mode
+
+- This build uses AGENTS.md bootstrap.
+- Before planning or implementation, resolve context from {{GLOBAL_CONTEXT_INDEX}}.
+- If the global index is missing, recommend `$onboard` before `$request`. Do not pretend the missing context does not matter.
+- Use `shift-ax doctor` when setup, launcher availability, or topic state looks unhealthy.
+- Use `shift-ax resolve-context` before answering when relevant documents may exist.
+- Use `shift-ax run-request` to create the request-scoped topic/worktree, run the planning interview, write brainstorming/spec/plan artifacts plus `execution-handoff.json`, and pause at the human planning-review gate.
+- Use `shift-ax approve-plan` after the human reviewer signs off.
+- If the reviewed plan requires shared policy or base-context doc changes, record them first with `shift-ax sync-policy-context --topic <dir> --summary "<what changed>" [--path <doc>]... [--entry "Label -> path"]...`.
+- Then resume with `shift-ax run-request --topic <dir> --resume` for automatic review and commit. Use `--no-auto-commit` only when a human explicitly wants the final commit step held back.
+- If downstream review or CI fails after the topic looked ready, use `shift-ax react-feedback --topic <dir> --kind <review-changes-requested|ci-failed> --summary "<text>"` to reopen implementation with a file-backed reaction trail.
+- Use `shift-ax launch-execution --platform codex --topic <dir> [--task-id <id>] [--dry-run]` when you need the concrete Codex or tmux launch commands from `execution-handoff.json`.
+- Use `shift-ax topic-status --topic <dir>` when you need a compact summary of phase, review gate, execution state, and last failure.
+- Use `shift-ax topics-status [--root DIR] [--limit N]` when you need a compact multi-topic view without leaving the CLI.
+- If a reviewed request hits a mandatory escalation trigger, persist that stop with `shift-ax run-request --topic <dir> --resume --escalation <kind>:<summary>` and resume only after human review with `--clear-escalations`.
+- Use `shift-ax worktree-plan` to inspect the preferred branch/worktree path for the topic.
+- Use `shift-ax worktree-create` before implementation begins and `shift-ax worktree-remove` when the topic worktree should be torn down.
+- Worktree runtime provenance is tracked in `platform/codex/upstream/worktree/provenance.md`.
+- Active imported worktree helpers currently include `resolveRepoRoot`, `ensureCodexManagedWorktree`, and `removeCodexManagedWorktree`.
+- Use `shift-ax review --run` before finalization and `shift-ax finalize-commit` only after the review gate allows commit.
+- Natural language is the primary user surface. Internal AX commands exist to support the flow, not replace the conversation.
+- In Shift AX Codex sessions, prefer `$onboard`, `$request <text>`, `$export-context`, `$doctor`, `$status`, `$topics`, `$resume <topic>`, `$review <topic>`, and `$help` as the visible product-shell commands.
+- Native product-shell skill files are installed under `.codex/skills/<name>/SKILL.md` for: `onboard`, `request`, `export-context`, `doctor`, `status`, `topics`, `resume`, and `review`.
+
+## Product-shell aliases
+
+Treat these as explicit Shift AX commands inside the session:
+
+- `$onboard` -> onboarding flow
+- `$doctor` -> repo/topic health
+- `$request <text>` -> new request-to-commit flow
+- `$status` -> current topic or repo status
+- `$topics` -> recent topics list
+- `$resume <topic>` -> resume a topic
+- `$review <topic>` -> run structured review

package/dist/platform/codex/scaffold/prompts/doctor.template.md

@@ -0,0 +1,11 @@
+---
+description: Run Shift AX health checks for the current repository.
+argument_hint: "[--topic <dir>]"
+---
+
+Run Shift AX doctor for the current repository.
+
+- If arguments specify a topic, use `shift-ax doctor --topic <dir>`.
+- Otherwise use `shift-ax doctor`.
+
+Summarize the repo health, base-context health, and any launcher warnings.

package/dist/platform/codex/scaffold/prompts/export-context.template.md

@@ -0,0 +1,20 @@
+---
+description: Explain how to share the user's Shift AX global knowledge base.
+argument_hint: ""
+---
+
+Do not build an archive.
+
+Explain that the user should share:
+
+- `~/.shift-ax/`
+
+And tell the recipient to place the shared files at the same location on their machine:
+
+- `~/.shift-ax/`
+
+Mention that the most important file is:
+
+- `~/.shift-ax/index.md`
+
+If useful, remind them that `$onboard` can refresh the profile before sharing.

package/dist/platform/codex/scaffold/prompts/onboard.template.md

@@ -0,0 +1,43 @@
+---
+description: Capture or refresh the user's global Shift AX knowledge base.
+argument_hint: "[optional note]"
+---
+
+This command is the most important setup step.
+
+Start by saying:
+
+> This step matters most. Please invest 10 minutes so Shift AX can understand how you work.
+
+Then run a conversational interview that captures:
+
+1. primary role summary
+2. work types
+3. related repositories for each work type
+4. per-repository working methods
+5. company/domain language
+
+For each work type and repository:
+
+- ask which directories matter
+- inspect the repository when a path is available
+- infer likely workflow details from real files
+- present your inferred workflow back to the user
+- ask them to correct anything wrong or missing
+
+When you have enough information:
+
+1. write `.ax/onboarding-input.json`
+2. if `{{GLOBAL_CONTEXT_INDEX}}` or other global knowledge files already exist, ask whether to overwrite them first
+3. persist with:
+   - `shift-ax onboard-context --root "<repo>" --input .ax/onboarding-input.json`
+   - add `--overwrite` only if the user explicitly agreed
+
+Keep the top-level knowledge base in `~/.shift-ax/` with:
+
+- `index.md` listing only titles and linked pages
+- linked work type pages
+- linked repository/procedure pages
+- linked domain-language pages
+
+After completion, remind the user to share `~/.shift-ax/` with teammates who do similar work.

package/dist/platform/codex/scaffold/prompts/onboarding.template.md

@@ -0,0 +1,43 @@
+---
+description: Capture or refresh the user's global Shift AX knowledge base.
+argument_hint: "[optional note]"
+---
+
+This command is the most important setup step.
+
+Start by saying:
+
+> This step matters most. Please invest 10 minutes so Shift AX can understand how you work.
+
+Then run a conversational interview that captures:
+
+1. primary role summary
+2. work types
+3. related repositories for each work type
+4. per-repository working methods
+5. company/domain language
+
+For each work type and repository:
+
+- ask which directories matter
+- inspect the repository when a path is available
+- infer likely workflow details from real files
+- present your inferred workflow back to the user
+- ask them to correct anything wrong or missing
+
+When you have enough information:
+
+1. write `.ax/onboarding-input.json`
+2. if `{{GLOBAL_CONTEXT_INDEX}}` or other global knowledge files already exist, ask whether to overwrite them first
+3. persist with:
+   - `shift-ax onboard-context --root "<repo>" --input .ax/onboarding-input.json`
+   - add `--overwrite` only if the user explicitly agreed
+
+Keep the top-level knowledge base in `~/.shift-ax/` with:
+
+- `index.md` listing only titles and linked pages
+- linked work type pages
+- linked repository/procedure pages
+- linked domain-language pages
+
+After completion, remind the user to share `~/.shift-ax/` with teammates who do similar work.

package/dist/platform/codex/scaffold/prompts/request.template.md

@@ -0,0 +1,19 @@
+---
+description: Start a new Shift AX request-to-commit flow.
+argument_hint: "<request>"
+---
+
+Treat everything after this command as the raw request text.
+
+If no request text was provided, ask for it before doing anything else.
+
+Then:
+
+1. resolve context from `{{GLOBAL_CONTEXT_INDEX}}` first
+2. if the global index is missing, stop and tell the user onboarding should come first because accuracy will drop
+3. ask whether they want to continue anyway
+4. only if they explicitly agree, bootstrap with `shift-ax run-request --request "<request>" --allow-missing-global-context`
+5. otherwise bootstrap with `shift-ax run-request --request "<request>"`
+6. explain the resulting topic path and that the workflow pauses at human plan review
+
+Never skip context grounding or the planning/review gates.

package/dist/platform/codex/scaffold/prompts/resume.template.md

@@ -0,0 +1,14 @@
+---
+description: Resume an approved Shift AX topic.
+argument_hint: "<topic-dir> [--verify-command <cmd> ...]"
+---
+
+Treat the first argument as the topic directory.
+
+Resume with:
+
+`shift-ax run-request --topic <topic-dir> --resume`
+
+If extra verification commands are given, append them as `--verify-command`.
+
+Explain whether the topic is blocked by escalation or policy sync if resume cannot continue.

package/dist/platform/codex/scaffold/prompts/review.template.md

@@ -0,0 +1,10 @@
+---
+description: Run structured Shift AX review for a topic.
+argument_hint: "<topic-dir>"
+---
+
+Run:
+
+`shift-ax review --topic <topic-dir> --run`
+
+Then summarize the review lanes, aggregate verdict, and remaining blockers.

package/dist/platform/codex/scaffold/prompts/shift-ax-bootstrap.template.md

@@ -0,0 +1,23 @@
+# Shift AX Codex Prompt Bootstrap
+
+- Before planning or implementation, resolve context from {{GLOBAL_CONTEXT_INDEX}}.
+- If the global index is missing, recommend `$onboard` before `$request`. Do not fake certainty.
+- Use `shift-ax doctor` when setup, launcher availability, or topic state looks unhealthy.
+- Use `shift-ax resolve-context` before answering when relevant documents may exist.
+- Use `shift-ax run-request` to create the request-scoped topic/worktree, run the planning interview, write brainstorming/spec/plan artifacts plus `execution-handoff.json`, and pause at the human planning-review gate.
+- Use `shift-ax approve-plan` after the human reviewer signs off.
+- If the reviewed plan requires shared policy or base-context doc changes, record them first with `shift-ax sync-policy-context --topic <dir> --summary "<what changed>" [--path <doc>]... [--entry "Label -> path"]...`.
+- Then resume with `shift-ax run-request --topic <dir> --resume` for automatic review and commit. Use `--no-auto-commit` only when a human explicitly wants the final commit step held back.
+- If downstream review or CI fails after the topic looked ready, use `shift-ax react-feedback --topic <dir> --kind <review-changes-requested|ci-failed> --summary "<text>"` to reopen implementation with a file-backed reaction trail.
+- Use `shift-ax launch-execution --platform codex --topic <dir> [--task-id <id>] [--dry-run]` when you need the concrete Codex or tmux launch commands from `execution-handoff.json`.
+- Use `shift-ax topic-status --topic <dir>` when you need a compact summary of phase, review gate, execution state, and last failure.
+- Use `shift-ax topics-status [--root DIR] [--limit N]` when you need a compact multi-topic view without leaving the CLI.
+- If a reviewed request hits a mandatory escalation trigger, persist that stop with `shift-ax run-request --topic <dir> --resume --escalation <kind>:<summary>` and resume only after human review with `--clear-escalations`.
+- Use `shift-ax worktree-plan` to inspect the preferred branch/worktree path for the topic.
+- Use `shift-ax worktree-create` before implementation begins and `shift-ax worktree-remove` when the topic worktree should be torn down.
+- Worktree runtime provenance is tracked in `platform/codex/upstream/worktree/provenance.md`.
+- Active imported worktree helpers currently include `resolveRepoRoot`, `ensureCodexManagedWorktree`, and `removeCodexManagedWorktree`.
+- Use `shift-ax review --run` before finalization and `shift-ax finalize-commit` only after the review gate allows commit.
+- Natural language is the primary user surface. Internal AX commands exist to support the flow, not replace the conversation.
+- In Shift AX Codex sessions, prefer `$onboard`, `$request <text>`, `$export-context`, `$doctor`, `$status`, `$topics`, `$resume <topic>`, `$review <topic>`, and `$help` as the visible product-shell commands.
+- Native product-shell skill files are installed under `.codex/skills/<name>/SKILL.md` for: `onboard`, `request`, `export-context`, `doctor`, `status`, `topics`, `resume`, and `review`.

package/dist/platform/codex/scaffold/prompts/status.template.md

@@ -0,0 +1,14 @@
+---
+description: Show Shift AX status for one topic or the repo.
+argument_hint: "[<topic-dir>]"
+---
+
+If a topic directory is provided, run:
+
+`shift-ax topic-status --topic <topic-dir>`
+
+Otherwise run:
+
+`shift-ax topics-status`
+
+Summarize the current phase, review gate, execution status, and blockers.

package/dist/platform/codex/scaffold/prompts/topics.template.md

@@ -0,0 +1,10 @@
+---
+description: List recent Shift AX topics for the current repository.
+argument_hint: "[--limit N]"
+---
+
+List recent topics with:
+
+`shift-ax topics-status`
+
+If the user supplied a limit, include it.

package/dist/platform/codex/scaffold/skills/doctor/SKILL.template.md

@@ -0,0 +1,11 @@
+---
+description: Run Shift AX health checks for the current repository.
+argument_hint: "[--topic <dir>]"
+---
+
+Run Shift AX doctor for the current repository.
+
+- If arguments specify a topic, use `shift-ax doctor --topic <dir>`.
+- Otherwise use `shift-ax doctor`.
+
+Summarize the repo health, base-context health, and any launcher warnings.

package/dist/platform/codex/scaffold/skills/export-context/SKILL.template.md

@@ -0,0 +1,20 @@
+---
+description: Explain how to share the user's Shift AX global knowledge base.
+argument_hint: ""
+---
+
+Do not build an archive.
+
+Explain that the user should share:
+
+- `~/.shift-ax/`
+
+And tell the recipient to place the shared files at the same location on their machine:
+
+- `~/.shift-ax/`
+
+Mention that the most important file is:
+
+- `~/.shift-ax/index.md`
+
+If useful, remind them that `$onboard` can refresh the profile before sharing.

package/dist/platform/codex/scaffold/skills/onboard/SKILL.template.md

@@ -0,0 +1,43 @@
+---
+description: Capture or refresh the user's global Shift AX knowledge base.
+argument_hint: "[optional note]"
+---
+
+This command is the most important setup step.
+
+Start by saying:
+
+> This step matters most. Please invest 10 minutes so Shift AX can understand how you work.
+
+Then run a conversational interview that captures:
+
+1. primary role summary
+2. work types
+3. related repositories for each work type
+4. per-repository working methods
+5. company/domain language
+
+For each work type and repository:
+
+- ask which directories matter
+- inspect the repository when a path is available
+- infer likely workflow details from real files
+- present your inferred workflow back to the user
+- ask them to correct anything wrong or missing
+
+When you have enough information:
+
+1. write `.ax/onboarding-input.json`
+2. if `{{GLOBAL_CONTEXT_INDEX}}` or other global knowledge files already exist, ask whether to overwrite them first
+3. persist with:
+   - `shift-ax onboard-context --root "<repo>" --input .ax/onboarding-input.json`
+   - add `--overwrite` only if the user explicitly agreed
+
+Keep the top-level knowledge base in `~/.shift-ax/` with:
+
+- `index.md` listing only titles and linked pages
+- linked work type pages
+- linked repository/procedure pages
+- linked domain-language pages
+
+After completion, remind the user to share `~/.shift-ax/` with teammates who do similar work.

package/dist/platform/codex/scaffold/skills/request/SKILL.template.md

@@ -0,0 +1,19 @@
+---
+description: Start a new Shift AX request-to-commit flow.
+argument_hint: "<request>"
+---
+
+Treat everything after this command as the raw request text.
+
+If no request text was provided, ask for it before doing anything else.
+
+Then:
+
+1. resolve context from `{{GLOBAL_CONTEXT_INDEX}}` first
+2. if the global index is missing, stop and tell the user onboarding should come first because accuracy will drop
+3. ask whether they want to continue anyway
+4. only if they explicitly agree, bootstrap with `shift-ax run-request --request "<request>" --allow-missing-global-context`
+5. otherwise bootstrap with `shift-ax run-request --request "<request>"`
+6. explain the resulting topic path and that the workflow pauses at human plan review
+
+Never skip context grounding or the planning/review gates.

package/dist/platform/codex/scaffold/skills/resume/SKILL.template.md

@@ -0,0 +1,14 @@
+---
+description: Resume an approved Shift AX topic.
+argument_hint: "<topic-dir> [--verify-command <cmd> ...]"
+---
+
+Treat the first argument as the topic directory.
+
+Resume with:
+
+`shift-ax run-request --topic <topic-dir> --resume`
+
+If extra verification commands are given, append them as `--verify-command`.
+
+Explain whether the topic is blocked by escalation or policy sync if resume cannot continue.

package/dist/platform/codex/scaffold/skills/review/SKILL.template.md

@@ -0,0 +1,10 @@
+---
+description: Run structured Shift AX review for a topic.
+argument_hint: "<topic-dir>"
+---
+
+Run:
+
+`shift-ax review --topic <topic-dir> --run`
+
+Then summarize the review lanes, aggregate verdict, and remaining blockers.

package/dist/platform/codex/scaffold/skills/status/SKILL.template.md

@@ -0,0 +1,14 @@
+---
+description: Show Shift AX status for one topic or the repo.
+argument_hint: "[<topic-dir>]"
+---
+
+If a topic directory is provided, run:
+
+`shift-ax topic-status --topic <topic-dir>`
+
+Otherwise run:
+
+`shift-ax topics-status`
+
+Summarize the current phase, review gate, execution status, and blockers.

package/dist/platform/codex/scaffold/skills/topics/SKILL.template.md

@@ -0,0 +1,10 @@
+---
+description: List recent Shift AX topics for the current repository.
+argument_hint: "[--limit N]"
+---
+
+List recent topics with:
+
+`shift-ax topics-status`
+
+If the user supplied a limit, include it.

package/dist/platform/codex/tmux.js

@@ -0,0 +1,45 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readImportedUpstreamSlice } from '../upstream-imports.js';
+import { buildCodexResizeHookName, buildCodexResizeHookTarget, } from './upstream/tmux/imported/resize-hooks.js';
+import { buildCodexRegisterResizeHookArgs, buildCodexUnregisterResizeHookArgs, } from './upstream/tmux/imported/resize-hook-registration.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+export function getCodexTmuxRuntime(rootDir) {
+    return {
+        support: 'imported-helpers',
+        multiplexer: 'tmux',
+        workspace_mode: 'leader-attached-layout',
+        naming: {
+            imported_helpers: [
+                'sanitizeCodexTeamName',
+                'buildCodexResizeHookTarget',
+                'buildCodexResizeHookName',
+            ],
+        },
+        upstream_boundary: {
+            import_root: join(rootDir, 'platform', 'codex', 'upstream', 'tmux'),
+            provenance_doc: join(rootDir, 'platform', 'codex', 'upstream', 'tmux', 'provenance.md'),
+            planned_upstream_modules: ['oh-my-codex/src/team/tmux-session.ts'],
+            active_imports: [
+                readImportedUpstreamSlice(join(HERE, 'upstream', 'tmux', 'imported', 'provenance.json')),
+                readImportedUpstreamSlice(join(HERE, 'upstream', 'tmux', 'imported', 'resize-hooks.provenance.json')),
+                readImportedUpstreamSlice(join(HERE, 'upstream', 'tmux', 'imported', 'resize-hook-registration.provenance.json')),
+            ],
+        },
+    };
+}
+export function buildCodexLeaderAttachedHookIdentity(teamName, sessionName, windowIndex, hudPaneId) {
+    return {
+        target: buildCodexResizeHookTarget(sessionName, windowIndex),
+        hookName: buildCodexResizeHookName(teamName, sessionName, windowIndex, hudPaneId),
+    };
+}
+export function buildCodexResizeHookRegistration(sessionName, windowIndex, teamName, hudPaneId) {
+    const identity = buildCodexLeaderAttachedHookIdentity(teamName, sessionName, windowIndex, hudPaneId);
+    return {
+        target: identity.target,
+        hookName: identity.hookName,
+        registerArgs: buildCodexRegisterResizeHookArgs(identity.target, identity.hookName, hudPaneId),
+        unregisterArgs: buildCodexUnregisterResizeHookArgs(identity.target, identity.hookName),
+    };
+}

package/dist/platform/codex/upstream/tmux/imported/resize-hook-registration.js

@@ -0,0 +1,37 @@
+const HUD_TMUX_TEAM_HEIGHT_LINES = 3;
+const TMUX_HOOK_INDEX_MAX = 2147483647;
+function shellQuoteSingle(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildBestEffortShellCommand(command) {
+    return `${command} >/dev/null 2>&1 || true`;
+}
+function buildNestedTmuxShellCommand(command) {
+    return `tmux ${command}`;
+}
+function buildHudPaneTarget(hudPaneId) {
+    const trimmed = hudPaneId.trim();
+    return trimmed.startsWith('%') ? trimmed : `%${trimmed}`;
+}
+function buildHudResizeCommand(hudPaneId, heightLines = HUD_TMUX_TEAM_HEIGHT_LINES) {
+    return `resize-pane -t ${buildHudPaneTarget(hudPaneId)} -y ${heightLines}`;
+}
+function buildResizeHookSlot(hookName) {
+    let hash = 0;
+    for (let i = 0; i < hookName.length; i++) {
+        hash = (hash * 31 + hookName.charCodeAt(i)) | 0;
+    }
+    return `client-resized[${Math.abs(hash) % TMUX_HOOK_INDEX_MAX}]`;
+}
+/**
+ * Imported from oh-my-codex.
+ * Source: oh-my-codex/src/team/tmux-session.ts
+ * Commit: fabb3ce0b96e42c20feb2940c74f2aa5addb8cee
+ */
+export function buildCodexRegisterResizeHookArgs(hookTarget, hookName, hudPaneId, heightLines = HUD_TMUX_TEAM_HEIGHT_LINES) {
+    const resizeCommand = shellQuoteSingle(buildBestEffortShellCommand(buildNestedTmuxShellCommand(buildHudResizeCommand(hudPaneId, heightLines))));
+    return ['set-hook', '-t', hookTarget, buildResizeHookSlot(hookName), `run-shell -b ${resizeCommand}`];
+}
+export function buildCodexUnregisterResizeHookArgs(hookTarget, hookName) {
+    return ['set-hook', '-u', '-t', hookTarget, buildResizeHookSlot(hookName)];
+}

package/dist/platform/codex/upstream/tmux/imported/resize-hooks.js

@@ -0,0 +1,29 @@
+function normalizeTmuxHookToken(value) {
+    const normalized = value
+        .replace(/[^A-Za-z0-9_-]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return normalized === '' ? 'unknown' : normalized;
+}
+function normalizeHudPaneToken(hudPaneId) {
+    const trimmed = hudPaneId.trim();
+    const withoutPrefix = trimmed.startsWith('%') ? trimmed.slice(1) : trimmed;
+    return normalizeTmuxHookToken(withoutPrefix);
+}
+/**
+ * Imported from oh-my-codex.
+ * Source: oh-my-codex/src/team/tmux-session.ts
+ * Commit: fabb3ce0b96e42c20feb2940c74f2aa5addb8cee
+ */
+export function buildCodexResizeHookTarget(sessionName, windowIndex) {
+    return `${sessionName}:${windowIndex}`;
+}
+export function buildCodexResizeHookName(teamName, sessionName, windowIndex, hudPaneId) {
+    return [
+        'omx_resize',
+        normalizeTmuxHookToken(teamName),
+        normalizeTmuxHookToken(sessionName),
+        normalizeTmuxHookToken(windowIndex),
+        normalizeHudPaneToken(hudPaneId),
+    ].join('_');
+}

package/dist/platform/codex/upstream/tmux/imported/sanitize-team-name.js

@@ -0,0 +1,18 @@
+/**
+ * Imported from oh-my-codex.
+ * Source: oh-my-codex/src/team/tmux-session.ts
+ * Commit: fabb3ce0b96e42c20feb2940c74f2aa5addb8cee
+ */
+export function sanitizeCodexTeamName(name) {
+    const lowered = name.toLowerCase();
+    const replaced = lowered
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-/, '')
+        .replace(/-$/, '');
+    const truncated = replaced.slice(0, 30).replace(/-$/, '');
+    if (truncated.trim() === '') {
+        throw new Error('sanitizeTeamName: empty after sanitization');
+    }
+    return truncated;
+}