chore(deps-dev): bump typescript from 5.9.3 to 6.0.2 in /frontend

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__docker-mcp__get-logs"
+    ]
+  }
+}

.coderabbit.yaml

@@ -166,6 +166,7 @@ reviews:
     drafts: false
     base_branches:
       - main
+      - main-dev
 
   tools:
     # ── Python Static Analysis ──

.codex/.gitignore

@@ -0,0 +1,3 @@
+# Ephemeral Codex session artifacts
+session/*
+!session/.gitkeep

.codex/README.md

@@ -0,0 +1,39 @@
+# Codex Repo Layer
+
+This directory contains the repo-local Codex harness surface for Pythinker.
+
+## Ownership
+
+- `AGENTS.md`: repo law and current repo constraints
+- `instructions.md`: engineering behavior and communication rules
+- `skills/`: workflow guidance for recurring task types
+- `.codex/`: Codex-local hooks, session artifacts, and harness glue
+- `.opencode/` and `.cursor/`: downstream adapters that should follow the Codex-first contract
+
+## Scope
+
+Use `.codex/` for:
+
+- hook entrypoints and wrappers
+- Codex session artifacts
+- local harness README and utilities
+
+Do not move repo law or shared engineering rules into this directory.
+
+## Session Artifacts
+
+- `.codex/session/` is for ephemeral local artifacts generated during Codex sessions
+- reviewed patterns belong in `docs/superpowers/observations/`, not in ephemeral session files
+
+## Phase-1 Hooks
+
+Planned phase-1 governance hooks:
+
+- `session-start`
+- `session-end`
+- `quality-gate`
+- `compact-reminder`
+- `mcp-health`
+- `doc-write-warning`
+
+These hooks should stay low-noise and review-friendly.

.codex/commands/README.md

@@ -0,0 +1,44 @@
+# Codex Command Equivalents
+
+This repo does not depend on a custom slash-command system for Codex. Use these thin command equivalents instead.
+
+## Planning
+
+- `/plan`
+  - Use `skills/pythinker-plan-execute/SKILL.md`
+  - Store plans in `docs/superpowers/plans/`
+
+## Review
+
+- `/review`
+  - Use `skills/pythinker-review/SKILL.md`
+
+## Verify
+
+- `/verify`
+  - Use `skills/pythinker-verification/SKILL.md`
+  - Or run `node .codex/hooks/quality-gate.js` to print the likely verification path
+
+## Harness Audit
+
+- `/harness-audit`
+
+```bash
+python3 scripts/ai/harness_audit.py
+```
+
+## Skill Stocktake
+
+- `/skill-stocktake`
+
+```bash
+python3 scripts/ai/skill_stocktake.py
+```
+
+## Session Summary
+
+- `/session-summary`
+
+```bash
+python3 scripts/ai/session_summary.py
+```

.codex/hooks/README.md

@@ -0,0 +1,26 @@
+# Codex Hooks
+
+These scripts are the low-noise phase-1 governance hooks for Pythinker.
+
+## Runtime Flags
+
+- `PYTHINKER_HOOK_PROFILE=minimal|standard|strict`
+- `PYTHINKER_DISABLED_HOOKS=hook1,hook2`
+
+Use `run-with-flags.js` to gate hooks by profile rather than wiring profile logic into each script.
+
+## Hooks
+
+- `session-start.js`: writes a small session snapshot to `.codex/session/`
+- `session-end.js`: writes a small end-of-session summary to `.codex/session/`
+- `quality-gate.js`: prints the likely verification commands for the current change set
+- `compact-reminder.js`: suggests compaction after enough hook invocations
+- `mcp-health.js`: reports whether repo MCP config files are present
+- `doc-write-warning.js`: warns when writing docs outside expected repo locations
+
+## Design Rules
+
+- Hooks should be low-noise.
+- Hooks should never rewrite repo guidance automatically.
+- Raw session artifacts stay under `.codex/session/`.
+- Reviewed patterns belong in `docs/superpowers/observations/`.

.codex/hooks/compact-reminder.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const { mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+const repoRoot = resolve(__dirname, "..", "..");
+const sessionDir = join(repoRoot, ".codex", "session");
+const counterPath = join(sessionDir, "compact-counter.json");
+const threshold = Number(process.env.PYTHINKER_COMPACT_THRESHOLD || "25");
+
+mkdirSync(sessionDir, { recursive: true });
+
+let count = 0;
+try {
+  count = JSON.parse(readFileSync(counterPath, "utf8")).count || 0;
+} catch {
+  count = 0;
+}
+
+count += 1;
+writeFileSync(counterPath, `${JSON.stringify({ count }, null, 2)}\n`, "utf8");
+
+if (count >= threshold && count % threshold === 0) {
+  process.stdout.write("[compact-reminder] Consider compacting at the next phase boundary.\n");
+}

.codex/hooks/doc-write-warning.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { relative, resolve } = require("node:path");
+
+const repoRoot = resolve(__dirname, "..", "..");
+const target = process.argv[2];
+
+if (!target) {
+  process.stdout.write("[doc-write-warning] no target path provided\n");
+  process.exit(0);
+}
+
+const relativePath = relative(repoRoot, resolve(target));
+const allowed =
+  relativePath.startsWith("docs/") ||
+  relativePath === "README.md" ||
+  relativePath === "AGENTS.md" ||
+  relativePath === "instructions.md";
+
+if (!allowed && relativePath.endsWith(".md")) {
+  process.stdout.write(`[doc-write-warning] ${relativePath} is outside the expected docs locations\n`);
+}

.codex/hooks/mcp-health.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const { existsSync } = require("node:fs");
+const { resolve } = require("node:path");
+
+const repoRoot = resolve(__dirname, "..", "..");
+const expected = ["mcp.json", "mcp.json.example"];
+
+for (const file of expected) {
+  const fullPath = resolve(repoRoot, file);
+  process.stdout.write(`[mcp-health] ${file}: ${existsSync(fullPath) ? "present" : "missing"}\n`);
+}

.codex/hooks/quality-gate.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const { execSync } = require("node:child_process");
+
+function safe(command) {
+  try {
+    return execSync(command, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+const changed = safe("git status --short").split("\n").filter(Boolean);
+const files = changed.map((line) => line.replace(/^\s*[A-Z?]{1,2}\s+/, ""));
+const touchedBackend = files.some((file) => file.startsWith("backend/"));
+const touchedFrontend = files.some((file) => file.startsWith("frontend/"));
+const harnessPrefixes = [
+  ".codex/",
+  ".opencode/",
+  ".cursor/",
+  "skills/",
+  "docs/",
+  "scripts/",
+  "tests/",
+];
+const touchedHarnessOnly =
+  files.length > 0 &&
+  files.every(
+    (file) =>
+      harnessPrefixes.some((prefix) => file.startsWith(prefix)) ||
+      file === "AGENTS.md" ||
+      file === "instructions.md" ||
+      file === "opencode.json",
+  );
+
+process.stdout.write("[quality-gate] recommended verification:\n");
+
+if (touchedBackend) {
+  process.stdout.write("- cd backend && ruff check . && ruff format --check . && pytest tests/\n");
+}
+if (touchedFrontend) {
+  process.stdout.write("- cd frontend && bun run lint:check && bun run type-check\n");
+}
+if (touchedHarnessOnly || files.length === 0) {
+  process.stdout.write("- targeted file/script checks for docs and harness-only changes\n");
+}

.codex/hooks/run-with-flags.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const { resolve, extname } = require("node:path");
+
+const VALID_PROFILES = new Set(["minimal", "standard", "strict"]);
+
+function normalizeProfile(rawProfile) {
+  return VALID_PROFILES.has(rawProfile) ? rawProfile : "standard";
+}
+
+function parseDisabledHooks(rawDisabled) {
+  if (!rawDisabled) return new Set();
+  return new Set(
+    rawDisabled
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+}
+
+function parseAllowedProfiles(rawProfiles) {
+  if (!rawProfiles) return new Set(["minimal", "standard", "strict"]);
+  return new Set(
+    rawProfiles
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+}
+
+function main() {
+  const [, , hookId, scriptPath, rawProfiles, ...scriptArgs] = process.argv;
+
+  if (!hookId || !scriptPath) {
+    process.stderr.write(
+      "Usage: run-with-flags.js <hook-id> <script-path> [allowed-profiles] [script-args...]\n",
+    );
+    process.exit(2);
+  }
+
+  const profile = normalizeProfile(process.env.PYTHINKER_HOOK_PROFILE);
+  const disabledHooks = parseDisabledHooks(process.env.PYTHINKER_DISABLED_HOOKS);
+  const allowedProfiles = parseAllowedProfiles(rawProfiles);
+
+  if (disabledHooks.has(hookId)) {
+    process.stdout.write(`[skip] ${hookId} disabled\n`);
+    return;
+  }
+
+  if (!allowedProfiles.has(profile)) {
+    process.stdout.write(`[skip] ${hookId} not enabled for profile ${profile}\n`);
+    return;
+  }
+
+  const absoluteScriptPath = resolve(scriptPath);
+  const executable = extname(absoluteScriptPath) === ".js" || extname(absoluteScriptPath) === ".mjs"
+    ? process.execPath
+    : absoluteScriptPath;
+  const args = executable === process.execPath ? [absoluteScriptPath, ...scriptArgs] : scriptArgs;
+
+  const result = spawnSync(executable, args, {
+    env: process.env,
+    stdio: "inherit",
+  });
+
+  if (typeof result.status === "number") {
+    process.exit(result.status);
+  }
+
+  process.exit(1);
+}
+
+main();

.codex/hooks/session-end.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const { execSync } = require("node:child_process");
+const { mkdirSync, writeFileSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+function safe(command) {
+  try {
+    return execSync(command, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+const repoRoot = resolve(__dirname, "..", "..");
+const sessionDir = join(repoRoot, ".codex", "session");
+mkdirSync(sessionDir, { recursive: true });
+
+const summary = {
+  ended_at: new Date().toISOString(),
+  branch: safe("git branch --show-current"),
+  head: safe("git rev-parse --short HEAD"),
+  status: safe("git status --short").split("\n").filter(Boolean),
+};
+
+writeFileSync(join(sessionDir, "latest-summary.json"), `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+process.stdout.write(`[session-end] tracked ${summary.status.length} changed entries\n`);

.codex/hooks/session-start.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const { execSync } = require("node:child_process");
+const { mkdirSync, writeFileSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+function safe(command) {
+  try {
+    return execSync(command, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+const repoRoot = resolve(__dirname, "..", "..");
+const sessionDir = join(repoRoot, ".codex", "session");
+mkdirSync(sessionDir, { recursive: true });
+
+const snapshot = {
+  started_at: new Date().toISOString(),
+  branch: safe("git branch --show-current"),
+  head: safe("git rev-parse --short HEAD"),
+  modified_files: safe("git status --short").split("\n").filter(Boolean),
+};
+
+writeFileSync(join(sessionDir, "latest-session.json"), `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+process.stdout.write(`[session-start] ${snapshot.branch || "unknown-branch"} ${snapshot.head || "unknown-head"}\n`);