docs: 2-tier architecture, canonical ownership, fact sync

.github/workflows/ai-command-policy.yml

@@ -34,7 +34,7 @@ jobs:
         with:
           script: |
             const body = (context.payload.comment?.body || "").toLowerCase();
-            const defaults = { implementation: "claude", review: "gemini" };
+            const defaults = { implementation: "claude", review: "codex" };
             const trustedAssociations = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 
             let kind = null;

.github/workflows/ai-review.yml

@@ -37,7 +37,7 @@ concurrency:
 
 jobs:
   ai-review:
-    # Gate-based path: gemini and codex (and unset default → gemini)
+    # Gate-based path: gemini and codex (and unset default → codex)
     if: >
       (
         github.event_name == 'workflow_dispatch' ||
@@ -75,19 +75,20 @@ jobs:
           set -euo pipefail
           selected="${{ vars.AI_REVIEW_AGENT }}"
           if [ -z "$selected" ]; then
-            selected="gemini"
+            selected="codex"
           fi
 
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             trigger_mode="${{ inputs.trigger_mode || 'skip' }}"
           else
             # All three backends (gemini, codex, claude) reject bot-posted
             # trigger comments on pull_request events, so the gate stays in
-            # skip mode. Gemini Code Assist auto-reviews on PR open; manual
-            # recovery uses `pnpm run review:switch` or a trusted human
-            # trigger comment. See docs_pallete_maker/project/devops/
-            # review-trigger-automation.md for the full constraint matrix
-            # and proposed automation.
+            # skip mode. Only Gemini Code Assist auto-reviews on PR open;
+            # codex and claude require a human-authored trigger on every
+            # review (open + synchronize). Manual recovery uses
+            # `pnpm run review:switch` or a trusted human trigger comment.
+            # See docs_pallete_maker/project/devops/review-trigger-automation.md
+            # for the full constraint matrix and proposed automation.
             trigger_mode="skip"
           fi
 

.specify/memory/constitution.md

@@ -53,10 +53,10 @@ through Vercel without relying on hidden session memory.
   Owns architecture, orchestration, CI/CD health, and repository memory, and
   is the default implementation agent. Runs from the user's local Claude Code
   terminal session and can dispatch other local agents via CLI when needed.
-- Gemini
-  Default review backend on GitHub pull requests via Gemini Code Assist.
 - Codex
-  Optional implementation and review agent behind explicit repository variable override.
+  Current default review backend via `@codex review` on PR comments (switched from Gemini on 2026-04-17). See `docs_pallete_maker/project/devops/ai-orchestration-protocol.md` for the full routing contract.
+- Gemini
+  Alternative review backend via Gemini Code Assist GitHub App; switch with `pnpm run review:switch -- --to gemini`.
 - GitHub Actions + Vercel
   Execute required checks, review normalization, previews, and production
   deployment.
@@ -76,8 +76,9 @@ through Vercel without relying on hidden session memory.
 
 ## macOS Local Runner Contract
 
-- Local orchestration is repository-owned and documented in
-  `docs_pallete_maker/project/devops/macos-local-runners.md`.
+- Local orchestration is repository-owned. Helper scripts live in `scripts/`
+  (`new-worktree.mjs`, `set-implementation-agent.mjs`,
+  `start-implementation-worker.mjs`, `publish-branch.mjs`).
 - Local agent selection state is stored under `.claude/` and is gitignored.
 - Local worktrees are created inside `<repoRoot>/.claude/worktrees/<slug>/`
   so they stay inside the repository and do not pollute the user's

AGENTS.md

@@ -5,8 +5,10 @@
 ## What Is pallete-maker?
 
 **pallete-maker** is a personal color palette creator. It lets a user pick a
-base color, build a harmonious palette of up to 10 colors using LCH-based
-harmony rules, preview the result on a grid, and export it as a PNG image.
+base color, build a harmonious palette of up to **15 colors (12 chromatic + 3
+achromatic; constants `MAX_TOTAL`, `MAX_CHROMATIC` in `src/scripts/harmony.mjs`)**
+using LCH-based harmony rules, preview the result on a grid, and export it as a
+PNG image.
 
 **Current implementation:** static single-file web app
 **Core dependencies:** chroma-js 2.4.2 (LCH harmony), html2canvas 1.4.1 (PNG export)
@@ -72,10 +74,11 @@ pallete-maker/
   - `AI_REVIEW_AGENT`
 - Default policy for this repository is:
   - implementation: `claude`
-  - review: `gemini`
+  - review: `codex` (switched from `gemini` on 2026-04-17; see `docs_pallete_maker/project/devops/ai-orchestration-protocol.md` for the canonical description)
 - Claude is the default implementation agent because it owns architecture, orchestration, CI/CD health, and repository memory, and is driven from the user's local Claude Code terminal session.
-- Gemini is the default review backend because it runs natively on GitHub pull requests via the Gemini Code Assist GitHub App.
-- Codex is available as an alternative review or implementation backend behind an explicit repository variable override.
+- Codex is the current default review backend via `@codex review` triggers on PR comments.
+- Gemini review stays wired via Gemini Code Assist GitHub App; switch with `pnpm run review:switch -- --to gemini`.
+- Claude review workflow (`claude-review.yml`) is **currently non-operational** (dead code pending cleanup PR; no `ANTHROPIC_API_KEY` configured, local runner rolled back).
 
 ## Review Guidelines
 
@@ -105,8 +108,10 @@ Changes must keep `pnpm run build` producing a deployable `dist/index.html` arti
 
 ### 4. One worker equals one worktree
 
-Do not run parallel implementation work in the main checkout. Use the local
-macOS runner flow from `docs_pallete_maker/project/devops/macos-local-runners.md`.
+Do not run parallel implementation work in the main checkout. Worktrees live
+under `<repoRoot>/.claude/worktrees/<slug>/` and are created via
+`scripts/new-worktree.mjs`. Local orchestration state is gitignored under
+`.claude/`.
 
 ### 5. Gemini review config is repository-owned
 
@@ -118,22 +123,12 @@ contract.
 
 Avoid adding more fixed-size offsets and viewport hacks unless strictly necessary. Prefer layout systems that can survive later migration to a modular frontend app.
 
-### 7. Auto-routing for orchestration capabilities
+### 7. Propose orchestration before non-trivial tasks
 
-Before executing a non-trivial task, evaluate whether any orchestration capability available to you (oh-my-claudecode (OMC) modes, subagents, multi-agent council, parallel execution, verification loops, etc.) is a better fit than a single-pass implementation. If one is, **propose it to the user in one short sentence with justification before starting**. Do not auto-launch; wait for user consent.
+Before a non-trivial task (multi-file change, refactor, research, verification loop, parallelizable work, unclear-cause debugging), propose the best-fit orchestration capability available to you in one short sentence with justification. Wait for user consent. Skip for trivial tasks (rename, one-line fix, quick question).
 
-Non-trivial triggers (any one):
-
-- Multi-file change, refactor, or migration
-- Codebase research where the answer is not obvious
-- Task that benefits from a verification / QA cycle
-- Parallelizable work (several independent subtasks)
-- Long-running autonomous work ("don't stop until done")
-- Debugging with unclear cause, tracing, or competing hypotheses
-
-Representative modes / agents to consider (Claude Code users have OMC modes like `/plan`, `/ralph`, `/ultrawork`, `/autopilot`, `/team`, `/trace`, `/debug`, `/ask` and subagents such as `executor`, `architect`, `critic`, `code-reviewer`, `debugger`, `tracer`, `verifier`, `planner`, `security-reviewer`, `test-engineer`, `explorer`, `designer`, `writer`). Codex / Gemini / other agents should propose their equivalent capabilities (planning modes, parallel task runners, review councils, etc.) before starting non-trivial work.
-
-Skip the proposal for trivial tasks: rename, one-line fix, simple question, quick status check. Minimal-friction principle — do not nag on small things.
+Claude Code specifics (OMC modes, subagents): see `CLAUDE.md § OMC orchestration`.
+Codex / Gemini / other agents: propose your equivalent capabilities (planning modes, parallel runners, review councils) before starting.
 
 ### 8. Always verify active branch and target refs before answering repo-state questions
 
@@ -147,13 +142,16 @@ workflow behavior:
 
 ## Reading Route — Implementing a Change
 
-1. `.specify/memory/constitution.md`
-2. `docs_pallete_maker/README.md`
-3. `docs_pallete_maker/project-idea.md`
-4. `docs_pallete_maker/project/frontend/frontend-docs.md`
-5. `docs_pallete_maker/project/devops/ai-orchestration-protocol.md`
-6. `docs_pallete_maker/project/devops/ai-pr-workflow.md`
-7. `specs/<feature-id>/spec.md`
-8. `specs/<feature-id>/plan.md`
-9. `specs/<feature-id>/tasks.md`
-10. Relevant app files and scripts
+This is the canonical reading order. `docs_pallete_maker/README.md` is a topical index (grouped by theme), not a reading order — defer to this list.
+
+1. `.specify/memory/constitution.md` — non-negotiable process rules
+2. `docs_pallete_maker/project-idea.md` — product facts (palette size, product state)
+3. `docs_pallete_maker/project/frontend/frontend-docs.md` — frontend architecture, grid, harmony, export
+4. `docs_pallete_maker/project/devops/ai-orchestration-protocol.md` — agent routing, default policy, review backends
+5. `docs_pallete_maker/project/devops/ai-pr-workflow.md` — PR gates and merge rules
+6. `docs_pallete_maker/project/devops/review-contract.md` — what each review backend produces
+7. `docs_pallete_maker/project/devops/review-trigger-automation.md` — why bot-posted triggers are rejected, active Tier 1
+8. `docs_pallete_maker/project/devops/delivery-playbook.md` — preview + production smoke
+9. `docs_pallete_maker/project/devops/vercel-cd.md` — Vercel deploy contract and security headers
+10. `specs/<feature-id>/spec.md`, `plan.md`, `tasks.md` — active feature
+11. Relevant app files and scripts

CLAUDE.md

@@ -1,6 +1,6 @@
 # pallete-maker
 
-Персональный инструмент для создания цветовых палитр: выбор базового цвета, построение гармоничной палитры до 10 цветов с проверкой LCH-гармоний и экспортом в PNG.
+Персональный инструмент для создания цветовых палитр: выбор базового цвета, построение гармоничной палитры до 15 цветов (12 хроматических + 3 ахроматических) с проверкой LCH-гармоний и экспортом в PNG.
 
 ## Текущий стек
 
@@ -10,7 +10,7 @@
 - Vercel Git integration для preview и production deploy
 - GitHub Actions для CI, guard и AI review orchestration
 - `.specify/`, `docs_pallete_maker/` и `specs/` как repository memory
-- Gemini Code Assist как default review backend
+- Codex как default review backend (см. `docs_pallete_maker/project/devops/ai-orchestration-protocol.md`)
 
 ## Важные правила
 
@@ -25,6 +25,8 @@
 - Локальный pre-push hook: `.claude/hooks/check-feature-memory-on-push.sh` (зарегистрирован в `.claude/settings.local.json` как PreToolUse на Bash) блокирует `git push`, если committed product-path changes требуют `specs/<id>/{spec,plan,tasks}.md` и спека нет. `.claude/` gitignored — на новой машине восстановить вручную из spec 013. Emergency bypass: закомментировать hook в `.claude/settings.local.json` или запушить из обычного терминала.
 - Не ломай `pnpm run build`: проект должен оставаться deployable как статический сайт
 - При review фокусируйся на mobile grid reflow, harmony rules correctness, PNG export safety, RU-строках и maintainability
+- Не создавай абстракции на один use-case. Если функция используется в одном месте, она не нуждается в конфигурируемости, plugin-интерфейсе или generic-параметрах. Добавляй обобщение только когда появляется второй реальный потребитель.
+- Для multi-step задач без отдельной спеки (рутинные 3-5 шагов: CDN-обновление, refactor одного модуля, миграция конфига) перед началом выпиши план: `шаг -> verify-условие`. Не делай молча и не запускай полный `/plan` ради 3 шагов.
 
 ## OMC orchestration (auto-routing)
 
@@ -62,4 +64,6 @@
 - PR loop: `docs_pallete_maker/project/devops/ai-pr-workflow.md`
 - Review contract: `docs_pallete_maker/project/devops/review-contract.md`
 - Review trigger automation: `docs_pallete_maker/project/devops/review-trigger-automation.md`
+- Delivery playbook: `docs_pallete_maker/project/devops/delivery-playbook.md`
 - Vercel CD: `docs_pallete_maker/project/devops/vercel-cd.md`
+- ADR index: `docs_pallete_maker/adr/README.md`

docs_pallete_maker/README.md

@@ -1,34 +1,28 @@
 # pallete-maker Docs Map
 
-`docs_pallete_maker/` is the durable memory layer for this repository.
-
-## What belongs here
-
-- stable product context
-- frontend architecture decisions
-- delivery and deployment rules
-- review and orchestration contracts
-- ADRs and operating playbooks
-
-## Main reading order
-
-1. `.specify/memory/constitution.md`
-2. `docs_pallete_maker/project-idea.md`
-3. `docs_pallete_maker/project/frontend/frontend-docs.md`
-4. `docs_pallete_maker/project/devops/ai-orchestration-protocol.md`
-5. `docs_pallete_maker/project/devops/ai-pr-workflow.md`
-6. `docs_pallete_maker/project/devops/review-trigger-automation.md`
-7. `specs/<feature-id>/spec.md`
-8. `specs/<feature-id>/plan.md`
-9. `specs/<feature-id>/tasks.md`
-
-## Structure
-
-- `adr/`
-  Architecture decision records and cross-cutting technical choices
-- `project-idea.md`
-  Product goals and current roadmap
-- `project/frontend/`
-  Frontend architecture and UI behavior notes
-- `project/devops/`
-  CI/CD, review, orchestration, and delivery workflow
+> Topical index. For the reading order, see `AGENTS.md § Reading Route`.
+
+`docs_pallete_maker/` is the durable memory layer for this repository. Entry points are `CLAUDE.md` (Claude-specific) and `AGENTS.md` (universal); this directory holds content they link into.
+
+## Structure by topic
+
+**Product**
+
+- `project-idea.md` — product facts (palette size, composition, roadmap). **Canonical source** for product facts.
+
+**Frontend**
+
+- `project/frontend/frontend-docs.md` — grid columns, harmony algorithm, build pipeline, accessibility.
+
+**Delivery & CI**
+
+- `project/devops/ai-orchestration-protocol.md` — agent routing, default review backend, native execution surfaces. **Canonical source** for review policy.
+- `project/devops/ai-pr-workflow.md` — PR gates and merge rules.
+- `project/devops/review-contract.md` — what each backend produces; severity rules.
+- `project/devops/review-trigger-automation.md` — bot-trigger rejection (Tier 1 active; design for Tier 2/3 in ADR).
+- `project/devops/delivery-playbook.md` — preview validation and production smoke.
+- `project/devops/vercel-cd.md` — Vercel deploy contract, security headers, supply-chain hygiene.
+
+**Decisions**
+
+- `adr/` — architecture decision records and cross-cutting choices.

docs_pallete_maker/adr/0001-review-trigger-design.md

@@ -0,0 +1,68 @@
+# ADR 0001 — Review Trigger Automation (Tier 2/3 design)
+
+**Status:** Design only. Not adopted. Tier 1 (`pnpm run review:switch`) is the active mitigation — see `docs_pallete_maker/project/devops/review-trigger-automation.md`.
+
+**Date:** 2026-04-18 (extracted from `review-trigger-automation.md` during docs consolidation)
+
+**Context:** All three supported review backends reject bot-posted trigger comments. Tier 1 (manual wrapper) is live and sufficient for current volume. This ADR captures the broader automation options so a future spec can adopt one without re-researching the problem.
+
+## Tier 2 — Local git post-push hook (semi-automatic)
+
+A husky-managed `post-push` hook that runs locally after every `git push` to a branch with an open PR. It detects the PR number via `gh pr view --json number` and posts the appropriate trigger comment using local `gh`.
+
+- Pros: fully automatic for local developer pushes.
+- Cons: does NOT run when agents or CI push (hooks are local only); needs husky wiring.
+
+## Tier 3 — GitHub Actions workflow with user PAT (most coverage)
+
+A new workflow listens on `pull_request: synchronize` and posts the trigger comment via `gh pr comment` using a repository secret containing a fine-grained PAT scoped to this repo.
+
+Sketch:
+
+```yaml
+name: Review Trigger
+on:
+  pull_request:
+    types: [synchronize]
+
+jobs:
+  post-trigger:
+    if: >
+      github.event.pull_request.head.repo.full_name == github.repository
+      && github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve trigger comment for backend
+        id: agent
+        run: |
+          agent="${{ vars.AI_REVIEW_AGENT }}"
+          case "${agent:-codex}" in
+            codex)  echo "trigger=@codex review"  >> "$GITHUB_OUTPUT" ;;
+            gemini) echo "trigger=/gemini review" >> "$GITHUB_OUTPUT" ;;
+            claude) echo "trigger=@claude review once" >> "$GITHUB_OUTPUT" ;;
+          esac
+      - name: Post trigger comment as repo owner
+        env:
+          GH_TOKEN: ${{ secrets.USER_REVIEW_PAT }}
+        run: |
+          gh pr comment "${{ github.event.pull_request.number }}" \
+            --body "${{ steps.agent.outputs.trigger }}" \
+            --repo "${{ github.repository }}"
+```
+
+- Pros: fully automatic for any push source (human, agent, CI); no local setup required on every dev machine.
+- Cons: introduces a PAT secret in the repo — must be fine-grained, scoped to `Pull requests: Write` on this single repo, and rotated annually.
+
+## PAT Security Requirements (if adopting Tier 3)
+
+- Fine-grained PAT, not classic token.
+- Resource owner: repo owner only.
+- Repository access: `kiaquila/pallete-maker` only (Selected repositories, not All).
+- Permissions: `Pull requests: Write`, `Contents: Read`. Nothing else.
+- Expiration: 1 year maximum. Calendar reminder for rotation.
+- Store in GitHub repo secret `USER_REVIEW_PAT`. Never log or echo.
+- Revoke immediately on any suspicious activity in the repo.
+
+## Recommendation
+
+Adopt Tier 1 now (active). Adopt Tier 3 when recurring friction from manual retriggers outweighs the PAT security posture review. Tier 2 is optional for developers who prefer local-only automation.

docs_pallete_maker/adr/README.md

@@ -3,10 +3,15 @@
 This folder stores durable cross-cutting decisions that should survive
 individual feature PRs.
 
-Examples:
+## Index
+
+- `0001-review-trigger-design.md` — Tier 2/3 automation design for review-trigger bypass (Tier 1 active; Tier 2/3 not adopted).
+
+## When to add an ADR
 
 - framework migrations
 - storage or persistence strategy
 - deployment model changes
 - palette architecture changes
 - agent orchestration changes that affect repository policy
+- any design that's captured in a devops doc but not currently adopted (extract as ADR to keep the devops doc about active behavior)