From 5c3da00030070608075c76afdd6574fbcd506238 Mon Sep 17 00:00:00 2001 From: Kristina Kurashova Date: Sat, 18 Apr 2026 14:36:05 -0300 Subject: [PATCH 1/4] docs: 2-tier architecture, canonical ownership, fact sync Co-Authored-By: Claude Opus 4.7 (1M context) --- .specify/memory/constitution.md | 11 +-- AGENTS.md | 60 +++++++------ CLAUDE.md | 8 +- docs_pallete_maker/README.md | 58 ++++++------- .../adr/0001-review-trigger-design.md | 68 +++++++++++++++ docs_pallete_maker/adr/README.md | 7 +- docs_pallete_maker/project-idea.md | 6 +- .../devops/ai-orchestration-protocol.md | 26 +++--- .../project/devops/ai-pr-workflow.md | 43 +++------- .../project/devops/delivery-playbook.md | 2 + .../project/devops/review-contract.md | 55 +++++------- .../devops/review-trigger-automation.md | 84 ++++--------------- .../project/devops/vercel-cd.md | 2 + .../project/frontend/frontend-docs.md | 4 +- 14 files changed, 216 insertions(+), 218 deletions(-) create mode 100644 docs_pallete_maker/adr/0001-review-trigger-design.md diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index e131870..33981b7 100644 --- a/.specify/memory/constitution.md +++ b/.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 `/.claude/worktrees//` so they stay inside the repository and do not pollute the user's diff --git a/AGENTS.md b/AGENTS.md index 71d06f1..6a8dbe3 100644 --- a/AGENTS.md +++ b/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 `/.claude/worktrees//` 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//spec.md` -8. `specs//plan.md` -9. `specs//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//spec.md`, `plan.md`, `tasks.md` — active feature +11. Relevant app files and scripts diff --git a/CLAUDE.md b/CLAUDE.md index 7f69b91..9de618b 100644 --- a/CLAUDE.md +++ b/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//{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` diff --git a/docs_pallete_maker/README.md b/docs_pallete_maker/README.md index e603676..72dab40 100644 --- a/docs_pallete_maker/README.md +++ b/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//spec.md` -8. `specs//plan.md` -9. `specs//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. diff --git a/docs_pallete_maker/adr/0001-review-trigger-design.md b/docs_pallete_maker/adr/0001-review-trigger-design.md new file mode 100644 index 0000000..76fc4dd --- /dev/null +++ b/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. diff --git a/docs_pallete_maker/adr/README.md b/docs_pallete_maker/adr/README.md index f8b58c8..f1048ef 100644 --- a/docs_pallete_maker/adr/README.md +++ b/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) diff --git a/docs_pallete_maker/project-idea.md b/docs_pallete_maker/project-idea.md index e437ff2..722d9d6 100644 --- a/docs_pallete_maker/project-idea.md +++ b/docs_pallete_maker/project-idea.md @@ -6,10 +6,12 @@ - browse a fixed palette of 51 curated colors and pick a base color - automatically see which colors are compatible based on an internal harmony algorithm (group + temperature rules) -- assemble a palette of up to 14 colors (11 chromatic + 3 achromatic) +- assemble a palette of **up to 15 colors** (`MAX_TOTAL = 15`, `MAX_CHROMATIC = 12` in `src/scripts/harmony.mjs`; 12 chromatic + 3 achromatic) - preview the selection in a bottom drawer, sorted achromatics-first - export the palette as a PNG image via html2canvas +> This file is the canonical source of truth for product facts (palette size, composition). Other docs reference this. + ## Current Product State The current app is a strong prototype: @@ -25,7 +27,7 @@ The repository now follows the standard delivery path: 1. PR-only changes 2. required checks in GitHub -3. AI review routing through repository policy with Gemini as the default reviewer +3. AI review routing through repository policy (current default: Codex; see `project/devops/ai-orchestration-protocol.md`) 4. Vercel preview deploys on PR 5. Vercel production deploys on merge to `main` 6. repository memory through `.specify/`, `docs_pallete_maker/`, and `specs/` diff --git a/docs_pallete_maker/project/devops/ai-orchestration-protocol.md b/docs_pallete_maker/project/devops/ai-orchestration-protocol.md index 3397f71..3d2928e 100644 --- a/docs_pallete_maker/project/devops/ai-orchestration-protocol.md +++ b/docs_pallete_maker/project/devops/ai-orchestration-protocol.md @@ -1,5 +1,7 @@ # AI Orchestration Protocol +> Audience: all agents. **Canonical source** for: agent routing, default review backend, supported agents, review normalization. Other docs reference this. Prereq: `.specify/memory/constitution.md`. Next: `ai-pr-workflow.md`. + ## Canonical Delivery Contract `pallete-maker` uses a PR-only delivery model. @@ -27,23 +29,26 @@ Agent routing is controlled by repository variables: - `codex` - `gemini` -Default policy in this repository: +Default policy in this repository (canonical): - implementation: `claude` -- review: `gemini` +- review: `codex` (switched from `gemini` on 2026-04-17) Claude is the canonical default implementation agent because it owns architecture, orchestration, CI/CD health, and repository memory for this repository, and is driven from the user's local Claude Code terminal session. -Gemini is the canonical default review backend because it runs natively on -GitHub pull requests via the Gemini Code Assist GitHub App. +Codex is the current default review backend. It runs natively on GitHub pull +requests via the ChatGPT Codex connector, triggered by `@codex review` comments +from trusted human actors. -Codex is available as an alternative review or implementation backend behind -an explicit `AI_REVIEW_AGENT=codex` or `AI_IMPLEMENTATION_AGENT=codex` override. +Gemini is available as an alternative review backend via the Gemini Code Assist +GitHub App. Switch with `pnpm run review:switch -- --to gemini`. -Claude review is a third-tier option behind an explicit `AI_REVIEW_AGENT=claude` -override and still requires `ANTHROPIC_API_KEY` when used via GitHub Actions. +Claude review (`claude-review.yml` workflow) is **currently non-operational**: +the workflow file remains in the repository as dead code pending a cleanup PR, +but `ANTHROPIC_API_KEY` is not configured and the local Claude runner was +rolled back. Do not select `AI_REVIEW_AGENT=claude` until this is restored. ## Local macOS Orchestration @@ -70,12 +75,13 @@ repository and do not pollute the user's `~/projects/` directory. Review normalization behavior: -- `gemini` is the default review backend and auto-reviews on PR open +- `codex` is the current default review backend; `@codex review` from a trusted + human posts a native PR review - pull-request `AI Review` runs support `codex`, `gemini`, and `claude` - manual Gemini and Codex review comments stay native-only to avoid canceling the PR-linked `AI Review` check - trusted human review commands dispatch the shared `AI Review` gate via - `workflow_dispatch` only for `claude` + `workflow_dispatch` only for `claude` (currently non-operational, see above) - the gate may reuse an existing same-head native review when a PR-linked `AI Review` run is rerun diff --git a/docs_pallete_maker/project/devops/ai-pr-workflow.md b/docs_pallete_maker/project/devops/ai-pr-workflow.md index 66930c9..11ac0b8 100644 --- a/docs_pallete_maker/project/devops/ai-pr-workflow.md +++ b/docs_pallete_maker/project/devops/ai-pr-workflow.md @@ -1,6 +1,8 @@ # AI Pull Request Workflow -This is the canonical PR loop for `pallete-maker`. +> Audience: all agents. **Canonical source** for: PR-specific gates and merge rules. Prereq: `.specify/memory/constitution.md` (Standard Feature Loop), `ai-orchestration-protocol.md` (agent routing). Next: `review-contract.md`. + +This doc covers PR-specific gates. The 10-step Standard Feature Loop lives in `.specify/memory/constitution.md § Standard Feature Loop` — do not duplicate here. ## Roles @@ -12,24 +14,6 @@ This is the canonical PR loop for `pallete-maker`. `main`. - A human remains the final merge authority. -## Standard Loop - -1. Start from current `main`. -2. Create or update one active `specs//` folder. -3. Create an isolated macOS worktree for the task under - `/.claude/worktrees//`. -4. Select the implementation and review agents for the branch. -5. Generate the implementation prompt from repository memory. -6. Implement only the scoped change on that branch. -7. Update `tasks.md`, docs, and tests or validation notes in the same PR. -8. Open or update the same PR. -9. Wait for: - - `baseline-checks` - - `guard` - - `AI Review` - - healthy Vercel preview deployment -10. Keep fixing the same branch until only human approval and merge remain. - ## Hard Gates - Product changes in `index.html`, `src/`, future app code, or runtime config do @@ -41,22 +25,15 @@ This is the canonical PR loop for `pallete-maker`. ## Review Contract -- Reviewer selection comes only from `AI_REVIEW_AGENT`. -- Supported review backends are `gemini`, `codex`, and `claude`. +Summary (details in `review-contract.md` and `ai-orchestration-protocol.md`): + - `AI Review` is the normalized required check regardless of the backend. +- Reviewer selection comes only from `AI_REVIEW_AGENT` (current default: `codex`). - Low-severity-only findings are advisory and non-blocking. -- With no repository override, the pull-request gate defaults to `gemini`. -- Auto-retrigger on `synchronize` is not supported for any backend: all - three reject bot-posted trigger comments. The gate therefore stays in - `trigger_mode=skip` on every `pull_request` event and passively waits - for a same-head native review. -- Initial PR review is covered by Gemini Code Assist's on-open auto-review. - After a new push on an already-open PR, a human must post the appropriate - native trigger comment (`/gemini review`, `@codex review`, or - `@claude review once`), or run `pnpm run review:switch -- --to ` - to flip backends and trigger the new reviewer in one shot. -- Manual Gemini and Codex review commands stay native-only so they do not - cancel the PR-linked `AI Review` check. +- After a new push, a human must post the native trigger comment + (`@codex review`, `/gemini review`, or `@claude review once`), or run + `pnpm run review:switch -- --to `. Bot-posted triggers are rejected + by all three backends — see `review-trigger-automation.md`. ## Merge-Ready Definition diff --git a/docs_pallete_maker/project/devops/delivery-playbook.md b/docs_pallete_maker/project/devops/delivery-playbook.md index 8b5688e..84bf408 100644 --- a/docs_pallete_maker/project/devops/delivery-playbook.md +++ b/docs_pallete_maker/project/devops/delivery-playbook.md @@ -1,5 +1,7 @@ # Delivery Playbook +> Audience: all agents. Canonical source for: preview validation checklist, merge rule, production smoke. Prereq: `ai-pr-workflow.md`. Next: `vercel-cd.md` (deploy contract). + This playbook covers preview validation before merge and production smoke after merge. diff --git a/docs_pallete_maker/project/devops/review-contract.md b/docs_pallete_maker/project/devops/review-contract.md index f6b6330..af2fb7c 100644 --- a/docs_pallete_maker/project/devops/review-contract.md +++ b/docs_pallete_maker/project/devops/review-contract.md @@ -1,41 +1,14 @@ # Review Contract -## Backend Trigger Constraints - -All three supported review backends require a **human-authored** trigger -on `pull_request: synchronize` events. Bot-posted trigger comments from -GitHub Actions (`github-actions[bot]`) are rejected silently or with an -explicit error by every backend: - -- **Gemini** — `gemini-code-assist[bot]` silently ignores bot-posted - `/gemini review` comments; the gate times out after 20 minutes. -- **Codex** — the connector replies "trigger did not come from a - connected human Codex account" and the `AI Review` gate fails fast. -- **Claude** — `claude-review.yml` gates on `author_association in -(OWNER, MEMBER, COLLABORATOR)` and drops anything authored by a bot. - -Gemini Code Assist's on-open auto-review (on `opened` and `ready_for_review`) -covers the initial review for free, but every new push on an already-open PR -needs a manual trigger. The canonical recovery path is -`pnpm run review:switch -- --to `, which flips the repository -variable, posts the correct native trigger comment as the current `gh` -user (human-authored, therefore trusted), and reruns the most recent -failed `AI Review` job. - -See `docs_pallete_maker/project/devops/review-trigger-automation.md` for the full -backend matrix. +> Audience: all agents. **Canonical source** for: per-backend review output format, severity rules, `AI_REVIEW_OUTCOME` schema. Prereq: `ai-orchestration-protocol.md` (agent routing). Sibling: `review-trigger-automation.md` (trigger mechanics). -## Gemini Review +## Backend Trigger Constraints (summary) -- Default review backend for `pallete-maker` -- Native GitHub PR review surface from `gemini-code-assist[bot]` -- Inline findings are expected to carry `Critical`, `High`, `Medium`, or `Low` -- `Low`-only findings are advisory -- `Critical`, `High`, and `Medium` findings block merge +All three backends reject bot-posted trigger comments on `pull_request: synchronize`; a human-authored trigger is required on every new push. Full backend matrix and mitigation Tiers: see `review-trigger-automation.md`. Canonical recovery: `pnpm run review:switch -- --to `. -## Codex Review +## Codex Review (current default) -- Optional fallback review backend, used when `AI_REVIEW_AGENT=codex` +- Current default review backend, used when `AI_REVIEW_AGENT=codex` - Native GitHub PR review surface from `chatgpt-codex-connector[bot]` - Inline findings must carry `P0` to `P3` - `P3`-only findings are advisory @@ -48,11 +21,23 @@ backend matrix. - If the timeline lookup is unavailable, the gate logs a warning and fails closed by waiting for formal review only. -## Claude Review +## Gemini Review + +- Alternative review backend, used when `AI_REVIEW_AGENT=gemini` +- Native GitHub PR review surface from `gemini-code-assist[bot]` +- Inline findings are expected to carry `Critical`, `High`, `Medium`, or `Low` +- `Low`-only findings are advisory +- `Critical`, `High`, and `Medium` findings block merge + +## Claude Review (currently non-operational) + +Retained for schema reference only. The `claude-review.yml` workflow is dead +code pending cleanup; `ANTHROPIC_API_KEY` is not configured and the local +runner was rolled back. Do not select `AI_REVIEW_AGENT=claude` until restored. + +Schema (when operational): -- Third-tier optional review backend, used when `AI_REVIEW_AGENT=claude` - Triggered by a human posting `@claude review once` on the PR -- Handled by the `claude-review.yml` workflow using `ANTHROPIC_API_KEY` - Final result is a top-level comment, not a formal GitHub review state - The comment must start with: diff --git a/docs_pallete_maker/project/devops/review-trigger-automation.md b/docs_pallete_maker/project/devops/review-trigger-automation.md index 39d263e..2983942 100644 --- a/docs_pallete_maker/project/devops/review-trigger-automation.md +++ b/docs_pallete_maker/project/devops/review-trigger-automation.md @@ -1,89 +1,41 @@ # Review Trigger Automation +> Audience: all agents. **Canonical source** for: bot-trigger rejection matrix, Tier 1 (active) recovery path. Tier 2/3 design: see `docs_pallete_maker/adr/0001-review-trigger-design.md`. + ## Problem All three supported review backends reject bot-posted trigger comments on `pull_request: synchronize` events: -- **Gemini** — `gemini-code-assist[bot]` silently ignores bot-posted `/gemini review` comments. - **Codex** — the connector replies `trigger did not come from a connected human Codex account`. +- **Gemini** — `gemini-code-assist[bot]` silently ignores bot-posted `/gemini review` comments. - **Claude** — `claude-review.yml` gates on `author_association in (OWNER, MEMBER, COLLABORATOR)` and drops bot-authored comments. -Gemini Code Assist auto-reviews PRs on `opened` and `ready_for_review`, which covers the first review on PR creation. But every subsequent push to an already-open PR requires a human to post the trigger comment. This creates recurring friction, especially when agents (Claude Code, Codex CLI) push updates to PR branches. +Gemini Code Assist auto-reviews PRs on `opened` and `ready_for_review`, which covers the first review on PR creation. Every subsequent push to an already-open PR requires a human-authored trigger. ## Core Insight The backends check whether the comment's `author_association` is a human role (`OWNER`, `MEMBER`, `COLLABORATOR`) and whether the posting account is a human GitHub account — NOT whether the auth is a PAT vs GitHub App token. A fine-grained Personal Access Token (PAT) belonging to the repository owner IS treated as a human trigger. -This means automation is possible by having GitHub Actions post trigger comments using a user PAT instead of the default `github.token` (which authenticates as `github-actions[bot]`). - -## Three Tiers of Automation - -### Tier 1 — Manual local wrapper (baseline, zero new secrets) - -Existing `pnpm run review:switch -- --to ` already posts the correct trigger comment using the local `gh` CLI auth (human-authored). A complementary `pnpm run review:retrigger` that only posts the current agent's trigger comment (without flipping the variable) would cover the "just rerun the review on my latest push" case. - -- Pros: no secrets; purely local; works today with minor script. -- Cons: manual invocation after every push. - -### Tier 2 — Local git post-push hook (semi-automatic) +## Tier 1 — Manual local wrapper (active, zero secrets) -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`. +Canonical recovery path. Use on every push that needs a re-review: -- 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:-gemini}" in - gemini) echo "trigger=/gemini review" >> "$GITHUB_OUTPUT" ;; - codex) echo "trigger=@codex 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 }}" ``` +pnpm run review:switch -- --to +``` + +The script: -- 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. +1. flips the `AI_REVIEW_AGENT` repository variable if different from current +2. posts the correct native trigger comment (`@codex review`, `/gemini review`, `@claude review once`) using the local `gh` CLI auth — human-authored, therefore trusted +3. reruns the most recent failed `AI Review` job on the current PR head -## PAT Security Requirements (if adopting Tier 3) +A complementary `pnpm run review:retrigger` (not yet implemented) would skip step 1 for the "just rerun the current agent" case. -- 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. +## Tier 2 and Tier 3 (design, not adopted) -## Recommendation +A local post-push git hook (Tier 2) and a GitHub Actions workflow posting trigger comments via a fine-grained PAT (Tier 3) would provide broader automation coverage but introduce setup or secret-management cost. The full design and PAT security requirements are captured in: -Adopt Tier 1 now (minimal script change). 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/0001-review-trigger-design.md` -This is documentation of the constraint; the actual adoption of Tier 1/2/3 is out of scope for the rollback PR and will be handled by a future spec. +Adopt when recurring friction from Tier 1 outweighs the PAT security posture review. diff --git a/docs_pallete_maker/project/devops/vercel-cd.md b/docs_pallete_maker/project/devops/vercel-cd.md index a57467b..231980e 100644 --- a/docs_pallete_maker/project/devops/vercel-cd.md +++ b/docs_pallete_maker/project/devops/vercel-cd.md @@ -1,5 +1,7 @@ # Vercel CD +> Audience: all agents. Canonical source for: Vercel deploy contract, security headers (CSP/HSTS/XFO), supply-chain hygiene (OSV, Dependabot, SHA-pinned actions). Prereq: `delivery-playbook.md`. + ## Deploy Model This repository uses **Vercel Git integration** as the canonical CD layer. diff --git a/docs_pallete_maker/project/frontend/frontend-docs.md b/docs_pallete_maker/project/frontend/frontend-docs.md index 68ac1bf..8c511b3 100644 --- a/docs_pallete_maker/project/frontend/frontend-docs.md +++ b/docs_pallete_maker/project/frontend/frontend-docs.md @@ -1,5 +1,7 @@ # Frontend Docs +> Audience: all agents. Canonical source for: grid columns, harmony algorithm, build pipeline, accessibility. Product facts (palette size) are in `docs_pallete_maker/project-idea.md`. + ## Current Architecture The application is a static SPA with a modular source layout: @@ -41,7 +43,7 @@ The picker grid displays all 51 colors of the fixed palette: Chartreuse → Emerald → Teal → Cobalt → Indigo → Violet → Fuchsia - each swatch is a `