From ed582a0ae98a6cf694fd88302ce02070d145fe11 Mon Sep 17 00:00:00 2001 From: ECWireless Date: Thu, 23 Jul 2026 04:49:37 +0000 Subject: [PATCH 1/2] chore: complete MVP release readiness --- .github/workflows/ci.yml | 79 +++++++++ IMPLEMENTATION_PLAN.md | 341 --------------------------------------- README.md | 106 ++++++++++++ 3 files changed, 185 insertions(+), 341 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..3bf44a4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,79 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + verify: + runs-on: ubuntu-latest + timeout-minutes: 20 + services: + postgres: + image: postgres:17 + env: + POSTGRES_DB: timetree_test + POSTGRES_PASSWORD: postgres + POSTGRES_USER: postgres + options: >- + --health-cmd "pg_isready -U postgres -d timetree_test" + --health-interval 5s + --health-timeout 5s + --health-retries 10 + ports: + - 5432:5432 + env: + ALLOWED_EMAIL: ci-user@example.test + BETTER_AUTH_SECRET: synthetic-ci-auth-secret-with-at-least-32-characters + BETTER_AUTH_URL: http://127.0.0.1:3187 + DATABASE_URL: postgres://postgres:postgres@127.0.0.1:5432/timetree_test + DATABASE_URL_UNPOOLED: postgres://postgres:postgres@127.0.0.1:5432/timetree_test + GOOGLE_CLIENT_ID: synthetic-google-client-id + GOOGLE_CLIENT_SECRET: synthetic-google-client-secret + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Install pnpm + uses: pnpm/action-setup@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Apply migrations + run: pnpm db:migrate + + - name: Lint + run: pnpm lint + + - name: Type check + run: pnpm typecheck + + - name: Run unit tests + run: pnpm test + + - name: Run integration tests + run: pnpm test:integration + + - name: Build + run: pnpm build + + - name: Install Chromium + run: pnpm exec playwright install --with-deps chromium + + - name: Run desktop and mobile browser smoke tests + run: >- + pnpm test:e2e + --grep "renders the signed-out foundation|loads the dashboard" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md deleted file mode 100644 index 89a00db..0000000 --- a/IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,341 +0,0 @@ -# TimeTree MVP Implementation Plan - -Status: Approved for implementation - -This plan implements [`SPEC.md`](./SPEC.md) in small, demonstrable slices. The -spec is authoritative when this plan is ambiguous. - -## Execution rules - -- Complete and verify one phase before starting the next. -- Each phase must leave the application runnable. -- Add no feature, abstraction, datastore, service, or deployment dependency that - is not required by the current phase and the MVP spec. -- Keep business rules in small server/domain modules rather than embedding them - in components. -- Protect every product read and mutation with one centralized guard that checks - a validated session, verified normalized allowlist email, and owner scope from - the first database-backed phase. -- Make every schema change through a committed SQL migration. -- Keep credentials, machine-specific paths, and local infrastructure details out - of tracked files. -- Prefer a straightforward implementation that can be replaced later over a - generalized system for hypothetical requirements. - -## Phase 1 — Project foundation - -Status: Complete - -### Build - -- Scaffold a Next.js 16 App Router application with React, strict TypeScript, - Tailwind CSS, ESLint, and `pnpm`. -- Record the package-manager version and commit the lockfile. -- Establish the minimal source layout for routes, components, domain logic, - database code, and tests. -- Add server-only environment validation and a placeholder-only `.env.example`. - Ensure `.env` and all local variants are ignored. -- Add the Coopa color tokens, Inter font stack, global focus treatment, and the - exact Coopa favicon. -- Configure Vitest and Playwright without adding application-specific test - helpers yet. - -### Verify - -- Lint, type checking, unit-test runner, production build, and the focused - Playwright smoke tests all pass. -- At desktop and mobile viewports, Playwright loads the initial route, finds the - stable TimeTree page landmark and title, detects no page error, and confirms - the document has no horizontal overflow. -- The initial page renders the intended minimal dark visual foundation at desktop - and mobile widths. -- A repository scan finds no credential or machine-specific local detail. - -## Phase 2 — Persistence and single-account authentication - -Status: Complete - -### Build - -- Add Drizzle ORM, Drizzle Kit, `pg`, Zod, Better Auth, and the official Better - Auth Drizzle adapter. -- Define Better Auth's generated tables and the three product tables from the - spec. -- Add database checks and indexes for positive durations, timestamp pairing, - non-negative rate cents, sibling reads, entry history reads, owner-scoped - relationships, one active timer per node, and deferred unique sibling - positions including the root sibling group. -- Generate and review the initial SQL migration. -- Add one shared server-only database client using `DATABASE_URL`; migration - commands prefer `DATABASE_URL_UNPOOLED` when supplied. -- Configure Google sign-in, rejection before usable access for non-allowed - accounts, sign-out, session lookup, and protected-route redirects. -- Add one centralized server authorization guard that rechecks verified, - normalized session email against the current exact-email allowlist on every - protected read and action. -- Render a minimal branded sign-in state at `/` and an authenticated empty - dashboard at the same route. - -### Verify - -- Migrations apply cleanly to an empty PostgreSQL database and are idempotently - recognized as already applied on the next run. -- Schema integration tests prove the ownership and active-timer uniqueness - constraints. -- The configured Google account can enter the dashboard; another account is - rejected without creating usable application access. -- Unverified email, a disallowed account, and a retained session after an - allowlist change all fail the centralized guard. -- A missing or invalid session cannot read the dashboard or invoke a product - action. - -## Phase 3 — Usable node tree - -Status: Complete - -### Build - -- Implement `getDashboardData()` and pure functions that assemble the flat node - list into an ordered tree. -- Implement root and child creation, inline title editing, description editing, - and explicit/inherited rate editing. -- Assign new siblings the next integer position. When sibling order changes, - rewrite that sibling group to contiguous integer positions in one transaction; - do not introduce fractional ranking keys. Serialize or retry conflicting - writes against the deferred uniqueness constraint. -- Add node selection through the `?node=` query parameter, breadcrumbs, - expand/collapse, inline child creation, and the desktop two-pane shell. -- Add the narrow-screen tree/detail navigation behavior. -- Render zero-state direct hours, rolled-up hours, and value without implementing - entries prematurely. - -### Verify - -- Unit tests cover tree assembly, ordering, breadcrumbs, inherited rates, and - malformed/orphaned data handling. -- Integration tests cover owner-scoped create and update actions. -- A concurrent sibling-create test proves positions remain unique and - contiguous. -- A user can build and edit a several-level hierarchy without leaving the - dashboard. -- Refresh and browser Back preserve the selected-node behavior defined by the - URL. - -## Phase 4 — Tree organization and lifecycle - -Status: Complete - -### Build - -- Implement transactional moves to a parent and sibling position. -- Reject self-parenting, descendant cycles, cross-owner destinations, and moves - of incomplete nodes beneath completed parents. -- Add drag-and-drop reordering and the searchable, keyboard-operable "Move To..." - dialog using the same server action. -- Add client-side title search with breadcrumb results and jump-to-node behavior. -- Implement recursive completion, completed-node filtering, reopening with its - ancestor path, and preservation of descendant completion state. -- Block completion when an active timer exists in the subtree. -- Use consistent row locking for move and lifecycle operations so concurrent - completion, reopening, movement, and later timer starts preserve invariants. -- Implement confirmed deletion of history-free subtrees, relying on restrictive - timer and entry foreign keys as the final concurrency guard. - -### Verify - -- Integration tests cover reparenting, sibling reordering, cycle rejection, - recursive completion, reopening, completion blocking, and safe deletion. -- Race tests cover a destination completing during a move and timer start racing - recursive completion. -- Pointer drag and "Move To..." produce identical persisted structures. -- Completed-node visibility and search/jump behavior work at desktop and mobile - widths. - -## Phase 5 — Manual time ledger and rates - -Phase 5 is delivered as three sequential PR-sized units. Before beginning each -unit, debrief its goal, non-goals, user-visible outcome, technical approach, -dependencies, sequential tasks, acceptance criteria, verification, commit and -PR boundary, and independent-review strategy with the user, then obtain explicit -approval. Complete the full verification, review, QA, and commit gates for one -unit before beginning the next. - -### PR 5.1 — Manual ledger foundation - -Status: Complete - -#### Build - -- Implement compact duration parsing and formatting as pure functions. -- Add duration-only and exact-range manual entry forms with local-date handling, - optional notes, resolved-rate preview, and explicit rate override. -- Implement create, edit, and confirmed permanent deletion of historical - entries. -- Preserve stored rates when timestamps, duration, notes, assignment, node - rates, or tree positions change unless the user explicitly edits the entry - rate. -- Load the selected node's 50 newest direct entries and append older pages with - a stable cursor. -- Display historical-entry durations and values according to the spec. - -#### Verify - -- Unit tests cover accepted and rejected duration strings, time formatting, - inheritance including explicit zero, and exact value math. -- Integration tests cover manual entry correction, deletion, rate snapshots, - pagination, and reassignment without silent rate recalculation. -- Manual historical entry remains available on a completed node. - -### PR 5.2 — Dashboard aggregates - -Status: Complete - -#### Build - -- Query direct entry aggregates once, then calculate descendant hours, priced - value, and unpriced-time flags in application code. -- Calculate exact rollups both with and without completed branches, and display - the variant selected by the "Show completed" control. -- Display direct and rolled-up durations, historical value, and unpriced-time - indicators according to the spec. - -#### Verify - -- Unit tests cover exact value math and tree rollups without double-counting. -- Integration tests cover priced and unpriced direct aggregates and owner - boundaries. -- Browser tests cover excluding completed branches by default and including - them when completed nodes are shown. -- Moving a subtree changes ancestor rollups without modifying any historical - entry. - -### PR 5.3 — Tree period filter - -Status: Complete - -#### Build - -- Add and migrate a reviewed composite owner/work-date/node index for whole-tree - period reads. -- Extend the owner-scoped dashboard aggregate read with validated all-time, - exact-day, and exact-month periods based exclusively on entry `workDate`. -- Apply the filtered direct aggregates to every node before calculating the - existing current-tree rollups, including the existing completed-branch - visibility behavior and exact historical value rules. -- Add a compact toolbar period selector with All time, Day, and Month modes plus - native date/month inputs. Represent explicit filters in the URL, derive new - day/month selections from browser-local calendar fields, and preserve the - filter while navigating between nodes. -- Keep the tree visible when a period has no matching entries and leave the - selected node's direct-entry history unfiltered. - -#### Verify - -- Unit tests cover exact day/month bounds, invalid period state, local calendar - defaults, canonical URL-state decisions, and filtered rollups without - double-counting. -- Integration tests cover all-time compatibility, day/month ownership - boundaries, empty periods, completed branches, unpriced time, work-date-based - assignment, and current-tree moves. A database-seeded active timer remains - excluded from every historical aggregate view. -- With a controlled browser timezone and date, switching from All time to Day or - Month selects the browser-local value. At desktop and mobile widths, changing - the period updates all tree and selected-node aggregate metrics plus the URL; - browser Back restores the prior period; node selection preserves the filter; - and nodes without matching direct or included-descendant entries remain - visible with zero metrics. The same browser path proves direct history and - pagination remain unfiltered, then creates or corrects an entry across the - selected boundary and observes refreshed metrics without losing URL state. - -## Phase 6 — Concurrent persistent timers - -Status: Complete - -### Build - -- Implement timer start with local work date and resolved-rate snapshot. -- Enforce one active timer per node while allowing concurrent timers on different - nodes. -- Implement atomic stop: consume the active timer, create its historical entry, - and commit both changes together. -- Add the sticky active-timers strip, shared one-second client clock, stop and - jump actions, and running state on tree rows. -- Reconstruct elapsed time exclusively from persisted start timestamps after - refresh or a closed tab. -- Keep active elapsed time out of historical totals until stop succeeds. - -### Verify - -- Integration tests cover concurrent starts, duplicate-node rejection, rate - snapshot timing, atomic stop, repeated-stop races, and completion blocking. -- Playwright proves two different nodes can run simultaneously, one node cannot - run twice, timers survive reload, and stopped time joins both the all-time and - matching selected day/month totals according to the timer's local `workDate` - captured at start, including when the timer later crosses midnight or a month - boundary. -- No background worker, polling service, or server-side ticking process exists. - -## Phase 7 — Accessibility, resilience, and release readiness - -### Build - -- Finish compact Coopa-derived styling across forms, tree rows, dialogs, empty - states, pending states, and errors without adding dashboard decoration. -- Complete keyboard behavior, accessible naming, focus-managed dialogs, reduced - motion, and non-chatty timer announcements. -- Add concise error handling for validation, stale actions, constraint races, - and database failures. -- Add the focused Playwright desktop/mobile workflows and a CI workflow for - lint, type checking, tests, build, and browser smoke coverage. -- Document generic setup, migrations, tests, and deployment in the README without - recording any developer-machine infrastructure. -- Configure Vercel production and preview environments with write-capable - pooled connections to the same production Neon branch, plus the production - Google callback and single allowed account. Give previews no direct migration - URL; document that preview code can mutate production data and must remain - compatible with the deployed production schema. -- Detect Vercel previews and replace Google sign-in with a concise link to the - canonical production application. Keep the production Better Auth base URL - and Google credentials for validated preview server configuration without - trusting preview origins or supporting authenticated preview QA. -- Classify each production migration, explicitly confirm the target, verify a - recent Neon recovery point and abort path, and ensure pre-deploy compatibility - with the running version. Use expand/deploy/contract sequencing when needed. -- Apply the production migration manually, deploy, and execute the release smoke - test with disposable data. - -### Verify - -- All automated checks pass from a clean checkout with supplied environment - values. -- Core workflows are keyboard-operable and usable at the agreed desktop and - mobile widths. -- Production sign-in, node operations, manual entry, concurrent timers, - historical correction, and cleanup work at `https://timetree.coopallc.com`. -- A final repository scan finds no secrets, local absolute paths, or local - infrastructure details. - -## Explicitly deferred - -- Multiple users per deployment, teams, organizations, invitations, and roles. -- Separate client/project/task models. -- Arbitrary-range reports, charts, invoice generation, billing workflows, - budgets, and exports. The focused whole-tree day/month filter remains in - scope. -- Tags, priorities, due dates, reminders, notifications, and integrations. -- Offline support, native applications, and calendar synchronization. -- Public product APIs, webhooks, background jobs, and scheduled work. -- Historical tree snapshots, closure tables, cached rollups, and event sourcing. -- Multi-currency support, decimal-hour preferences, themes, and persisted UI - preferences. -- A recycle bin, audit log, broad browser matrix, visual-regression service, and - load-testing system. - -## MVP completion gate - -The MVP is complete only when all seven phases satisfy their verification -criteria, the production release smoke test passes, and no deferred feature was -pulled into scope without an explicit spec change. - -After the user accepts the completed MVP and its final verification evidence, -delete this implementation plan as the last repository cleanup step. diff --git a/README.md b/README.md new file mode 100644 index 0000000..2b9325b --- /dev/null +++ b/README.md @@ -0,0 +1,106 @@ +# TimeTree + +TimeTree is a private, self-hostable work ledger organized as a nested tree. +It supports manual time entries, concurrent persistent timers, inherited hourly +rates, historical value, completion, search, and day or month filtering. + +The MVP is intentionally configured for one allowed Google account per +deployment. It is open source under the [MIT License](./LICENSE). + +## Requirements + +- Node.js 22 or newer +- Corepack and pnpm +- PostgreSQL 15 or newer +- Google OAuth credentials + +## Local setup + +1. Install dependencies: + + ```sh + corepack pnpm install + ``` + +2. Copy `.env.example` to `.env` and supply local values: + + - `DATABASE_URL`: pooled PostgreSQL connection used by the application + - `DATABASE_URL_UNPOOLED`: optional direct connection used by migrations + - `BETTER_AUTH_SECRET`: random secret containing at least 32 characters + - `BETTER_AUTH_URL`: public application origin, such as + `http://localhost:3000` + - `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`: Google OAuth credentials + - `ALLOWED_EMAIL`: the one verified Google account allowed to sign in + - `NEXT_ALLOWED_DEV_ORIGINS`: optional comma-separated development origins + + Local environment files are ignored by Git. Do not commit credentials. + +3. Configure the Google OAuth client with this callback URL: + + ```text + /api/auth/callback/google + ``` + +4. Apply the committed migrations: + + ```sh + corepack pnpm db:migrate + ``` + +5. Start the development server: + + ```sh + corepack pnpm dev + ``` + +## Verification + +Run the checks individually: + +```sh +corepack pnpm lint +corepack pnpm typecheck +corepack pnpm test +corepack pnpm test:integration +corepack pnpm build +corepack pnpm test:e2e +``` + +Integration and browser tests require a migrated PostgreSQL database through +the required `DATABASE_URL`. `DATABASE_URL_UNPOOLED` may additionally provide a +direct connection for database tooling and test setup. The Playwright +configuration uses synthetic authentication values and writes only synthetic +test records, which it removes after each workflow. + +Install the browser used by Playwright when needed: + +```sh +corepack pnpm exec playwright install chromium +``` + +## Database changes + +Schema changes belong in `src/db/schema.ts` and must be delivered as reviewed, +committed SQL migrations: + +```sh +corepack pnpm db:generate +corepack pnpm db:check +corepack pnpm db:migrate +``` + +Prefer a direct `DATABASE_URL_UNPOOLED` connection for migration commands. +Review generated SQL before applying it, back up important data, and keep each +migration compatible with the application version running during deployment. + +## Deployment + +Deploy the standard Next.js Node.js application to a host with PostgreSQL +connectivity. Configure the same environment names documented above in the +hosting platform, set `BETTER_AUTH_URL` to the canonical HTTPS origin, and add +that origin's Google callback URL to the OAuth client. + +Apply committed migrations deliberately before deploying code that requires +them. Keep secrets in the hosting platform rather than repository files. +Because TimeTree currently supports one account per deployment, changing +`ALLOWED_EMAIL` immediately revokes retained access for the previous account. From a896169c3d8cb0ddca65bb7e2a1889645b648359 Mon Sep 17 00:00:00 2001 From: ECWireless Date: Thu, 23 Jul 2026 05:05:00 +0000 Subject: [PATCH 2/2] chore: address MVP readiness review --- .github/workflows/ci.yml | 2 +- AGENTS.md | 26 ++++++++-------- SPEC.md | 3 -- docs/session-workflow.md | 64 ++++++++++++++++++---------------------- 4 files changed, 42 insertions(+), 53 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3bf44a4..dfcba12 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,7 @@ jobs: timeout-minutes: 20 services: postgres: - image: postgres:17 + image: postgres:15 env: POSTGRES_DB: timetree_test POSTGRES_PASSWORD: postgres diff --git a/AGENTS.md b/AGENTS.md index 6040465..2562abe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,26 +8,25 @@ These instructions apply to the entire repository unless a more specific nested Before editing files: 1. Read `SPEC.md`. -2. Read `IMPLEMENTATION_PLAN.md`. -3. Read `docs/session-workflow.md`. -4. Read `docs/model-effort-workflow.md` and recommend the lowest adequate effort +2. Read `docs/session-workflow.md`. +3. Read `docs/model-effort-workflow.md` and recommend the lowest adequate effort for the task. -5. Confirm the current branch and worktree state. -6. Identify likely change locations and read every applicable nested +4. Confirm the current branch and worktree state. +5. Identify likely change locations and read every applicable nested `AGENTS.md`. -7. Debrief the current phase or PR-sized unit with the user and obtain approval +6. Debrief the current PR-sized unit with the user and obtain approval before implementation. `SPEC.md` is the product and architecture authority. -`IMPLEMENTATION_PLAN.md` is the execution and verification authority. Resolve -conflicts explicitly before editing. +`docs/session-workflow.md` is the execution and verification process authority. +Resolve conflicts explicitly before editing. Do not jump directly into scaffolding, dependency installation, schema changes, or implementation. -## Phase alignment +## Work alignment -Before each phase or PR-sized unit, agree on: +Before each PR-sized unit, agree on: - goal, non-goals, and stopping point; - user-visible outcome; @@ -37,7 +36,7 @@ Before each phase or PR-sized unit, agree on: - commit and PR boundary; - proportional independent-review strategy. -Do not begin the next phase without a new debrief and explicit approval. +Do not begin the next unit without a new debrief and explicit approval. ## Git and publication @@ -73,15 +72,14 @@ Before declaring a PR-sized unit complete or preparing its PR: 6. Perform the approved QA when behavior or UI changed. 7. Resolve accepted QA findings, rerun affected checks, and obtain focused independent re-review of material post-review changes. -8. Update completed items in `IMPLEMENTATION_PLAN.md`, then review all changes - made since the independent-review snapshot. +8. Review all changes made since the independent-review snapshot. 9. Report verification and QA evidence, review disposition, deviations, and remaining scope to the user. Use sequential commit units: prepare only one commit's diff at a time, then complete its automated verification, review gate, user-approved QA when applicable, and explicit commit approval before beginning the next commit's implementation. Propose -the intended sequence during the phase debrief. Do not batch several prepared commit +the intended sequence during the unit debrief. Do not batch several prepared commit units into one review, QA, or approval cycle. After final evidence, obtain explicit approval, create the commit, and confirm it succeeded before implementing the next unit. Propose multiple PRs up front when the work would otherwise be too large for diff --git a/SPEC.md b/SPEC.md index 78182d1..148e137 100644 --- a/SPEC.md +++ b/SPEC.md @@ -620,6 +620,3 @@ DashboardPage (server) - Release verification covers sign-in, node creation, manual entry, timer start/stop, correction of the disposable entry, and cleanup of disposable data. - -The implementation sequence is maintained separately in -[`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md). diff --git a/docs/session-workflow.md b/docs/session-workflow.md index d83b6ce..eadcc0c 100644 --- a/docs/session-workflow.md +++ b/docs/session-workflow.md @@ -1,32 +1,27 @@ # Session Workflow -TimeTree is built phase by phase. Work may continue across different Codex -sessions, branches, and pull requests, so each session must rebuild its context -before implementation begins. +TimeTree work may continue across different Codex sessions, branches, and pull +requests, so each session must rebuild its context before implementation begins. ## Sources of truth - `SPEC.md` defines the approved product behavior, boundaries, and architecture. -- `IMPLEMENTATION_PLAN.md` defines the active phase sequence, tasks, and - verification gates. +- This workflow defines the planning, verification, review, and publication + process for each PR-sized unit. - Older attachments, handoffs, brainstorms, and chat history are context, not authority, unless the user explicitly promotes a decision into the spec. -Update the implementation plan as phase work lands. Do not remove or archive the -plan without explicit user approval. - ## Start every session this way Before editing files: -1. Read `SPEC.md` and `IMPLEMENTATION_PLAN.md`. -2. Read this workflow and `docs/model-effort-workflow.md`. -3. Recommend the lowest adequate effort level for the current task. -4. Confirm the current branch and worktree state. -5. Identify the directories likely to change and read every applicable nested +1. Read `SPEC.md`, this workflow, and `docs/model-effort-workflow.md`. +2. Recommend the lowest adequate effort level for the current task. +3. Confirm the current branch and worktree state. +4. Identify the directories likely to change and read every applicable nested `AGENTS.md` from the repository root down to those directories. -6. Confirm the current phase or PR-sized unit with the user. -7. Debrief the work: +5. Confirm the current PR-sized unit with the user. +6. Debrief the work: - intended user-visible outcome; - explicit non-goals and stopping point; - technical approach and any decisions still open; @@ -34,23 +29,23 @@ Before editing files: - verification commands and manual QA; - commit and PR boundary; - proportional independent-review gate. -8. Break the work into sequential tasks. -9. Propose the intended commit sequence. If the phase would be too large for a +7. Break the work into sequential tasks. +8. Propose the intended commit sequence. If the work would be too large for a comfortably reviewable pull request, propose multiple PR-sized units instead. - Commit units are sequential delivery gates, not labels applied after all phase + Commit units are sequential delivery gates, not labels applied after all implementation is complete. -10. Wait for explicit approval before beginning implementation. +9. Wait for explicit approval before beginning implementation. Repository-wide workflow files establish the process and approval boundaries. Nested guidance may refine instructions for its subtree but may not weaken repository-wide scope, privacy, security, approval, or review requirements. Stop and resolve conflicting guidance before editing. -## Phase planning checklist +## Work planning checklist Before writing code, agree on: -- phase goal and acceptance criteria; +- unit goal and acceptance criteria; - user-visible outcome; - effort recommendation; - technical approach; @@ -67,8 +62,8 @@ external service, datastore, or foundational pattern. ## Implementation rules -- Keep work within the agreed phase or PR-sized unit. -- Do not begin the next phase without a new debrief and approval. +- Keep work within the agreed PR-sized unit. +- Do not begin the next unit without a new debrief and approval. - Do not install dependencies until their purpose is agreed. - Do not start a development server unless the user expects a preview or it is required for agreed verification. @@ -86,7 +81,7 @@ Before declaring a PR-sized unit complete or preparing a pull request: 1. Run the agreed verification commands. 2. Review the diff for correctness, regressions, accessibility, maintainability, - unnecessary complexity, and phase-scope compliance. + unnecessary complexity, and scope compliance. 3. Perform a privacy and security pass: - confirm local environment files and secrets are ignored; - confirm no credentials, private hostnames, local absolute paths, private @@ -103,18 +98,17 @@ Before declaring a PR-sized unit complete or preparing a pull request: interface changes, and resolve accepted findings. 8. Rerun affected verification after QA-driven changes. Obtain focused independent re-review when those changes are material. -9. Update completed implementation-plan items within the commit scope, then - review every change made since the independent-review snapshot. Material +9. Review every change made since the independent-review snapshot. Material changes restart the affected verification and focused-review gates. -10. Summarize what changed, verification and QA evidence, plan deviations, and remaining - work. +10. Summarize what changed, verification and QA evidence, deviations, and + remaining work. 11. Keep the PR boundary narrow enough to review comfortably. Use sequential commit units. Prepare only one commit's diff at a time; complete its automated verification, independent review, user-approved QA when applicable, and explicit commit approval before implementing the next commit unit. Do not batch multiple prepared commits into a shared review, QA, or approval cycle. Present the -sequence during the phase debrief. After presenting the final evidence, obtain +sequence during the unit debrief. After presenting the final evidence, obtain explicit approval, create the commit, and confirm it succeeded before implementing the next commit unit. Staging, committing, pushing, and pull-request actions retain their separate approval boundaries. @@ -131,9 +125,9 @@ readiness—is the routine trigger. After accepted review findings are resolved, pause for the user-facing QA proposal and approval required above. Review every sequential commit unit against its intended base and scope. If a -phase spans multiple commits or PRs, also review the integrated phase diff against -the phase goal and acceptance criteria before the final phase commit or PR is -declared ready. +PR-sized unit includes multiple commit units, also review the integrated PR diff +against the PR-sized unit's goal and acceptance criteria before declaring the +PR ready. ### Reviewer count @@ -173,9 +167,9 @@ Useful specialties include: 7. Evaluate every finding rather than accepting it automatically. 8. Apply agreed fixes and rerun affected verification. 9. Request focused re-review of material fixes and disputed findings. -10. Record only material deferred or unresolved findings in - `IMPLEMENTATION_PLAN.md`; do not create permanent artifacts for fully - resolved routine review. +10. Report material deferred or unresolved findings to the user and record them + in a relevant durable project document only when approved. Do not create + permanent artifacts for fully resolved routine review. 11. Present final review evidence and disposition to the user, who remains the merge authority.