@odla-ai/cli 0.22.0 → 0.22.1

package/README.md

@@ -37,6 +37,26 @@ npx @odla-ai/cli runbook list                                      # what exists
 Reading works for any signed-in developer and needs no `odla.config.mjs` — the
 advice is most useful before there is a project.
 
+Runbooks tell an agent how to operate; PM tells every agent what this project is
+trying to prove, what is active, what was decided, and what is broken. Once the
+app is registered, start each session by reading its doing tasks, open bugs and
+goals, and recent decisions:
+
+```bash
+npx odla-ai pm task list --app <appId> --column doing
+npx odla-ai pm bug list --app <appId> --status open
+npx odla-ai pm goal list --app <appId> --status open
+npx odla-ai pm decision list --app <appId> --limit 20
+```
+
+Read the active task, linked goal, and comments before changing code. Without
+`--app`, list commands span every project the account co-owns, which is the
+right first view when coordinating several efforts; scope every write to the
+exact `appId` from that project's config. PM requires a registered app. Before
+the first provision, use a focused commit/checkpoint, then initialize PM and
+backfill that evidence immediately after registration. Never use a parallel
+status diary or put a secret in PM.
+
 **Runbooks are procedure; JSDoc is API.** What a function takes, returns, and
 guarantees is documented on the export itself, ships in the installed
 `.d.ts`, and renders per package at <https://odla.ai/docs>. A runbook will tell
@@ -93,11 +113,14 @@ npx @odla-ai/cli init --app-id my-app --name "My App"
 ```
 
 For a project you keep working in, install it as a dev dependency so the
-shorter `npx odla-ai` form works and the version is pinned by your lockfile:
+shorter `npx odla-ai` form works. ODLA is under active development: use a normal
+dependency declaration, commit the lockfile, and let `npm ci` reproduce the
+resolved graph:
 
 ```bash
-npm view @odla-ai/cli@0.16.6 version
-npm i -D --save-exact @odla-ai/cli@0.16.6
+npm view @odla-ai/cli version
+npm i -D @odla-ai/cli
+npm ls @odla-ai/cli
 ```
 
 ## Prerequisites
@@ -360,8 +383,8 @@ rolling-window/age-out, quota-backoff, retention/purge, or provider-derived
 mutation-id control. Public health remains aggregate rather than per calendar.
 
 The bundled build/migration skills add a passive pre-ship gate with
-`@odla-ai/security`: after the exact-version availability check, run
-`npm i -D --save-exact @odla-ai/security@0.3.1`, then
+`@odla-ai/security`: install it with a normal development range, commit the
+lockfile, then run `npm i -D @odla-ai/security`, followed by
 `npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
 The passive scan remains a separate binary: it makes no model calls and does
 not execute target code. After explicit redacted-source approval,
@@ -385,12 +408,11 @@ a conservative `Retry-After`. A provider-side `429` uses the sanitized
 carries a bounded `Retry-After` only when the upstream supplied one. The CLI
 does not echo arbitrary response text or silently change the admin-selected
 model.
-Before installing the exact release, require
-`npm view @odla-ai/security@0.3.1 version` to succeed before installation. An
-exact-version `E404` means the release is unavailable, not that the security
-preflight passed, and does not prove the package name is absent. odla's own
-engineering environment uses an equivalent internal gate; customer projects
-should use the published `odla-security` command above.
+Confirm `npm view @odla-ai/security version` succeeds and record the installed
+version from `npm ls @odla-ai/security` with the scan evidence. A registry
+failure blocks the preflight; it is not a clean scan. odla's own engineering
+environment uses an equivalent internal gate; customer projects should use the
+published `odla-security` command above.
 
 For a server-side, commit-pinned review, connect one repository through the
 source-read-only odla GitHub App. The CLI infers `owner/name` from a safe GitHub HTTPS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Agent-operable CLI for odla provisioning, calendar consent and sync lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",

package/skills/odla/SKILL.md

@@ -141,13 +141,19 @@ guessing which platform/credential steps need manual work. Then:
 
 odla has a project manager for agents — conformance goals, a kanban board, a
 decision log, and bugs, shared with the human and with every other agent working
-on the app. It is platform-side: nothing to install or provision. Start a session
-by reading it, and keep it current while you build:
+on the app. It is platform-side: there is nothing PM-specific to install or
+provision. Start a session by reading it, and keep it current while you build:
 
 ```cmd
 npx @odla-ai/cli pm task list --app <appId> --column doing
 ```
 
+The app must already be registered for ownership-scoped PM access. On a new
+project, use a focused commit/checkpoint only until the first provision, then
+initialize PM and backfill the approved early evidence immediately. Across
+several efforts, list without `--app` first, then scope every write to the exact
+project id.
+
 Record a **decision** the moment you make one (with what it rules out), file a
 **bug** the moment you notice one, and move a **task** when the work moves. A
 decision you don't record is one the next agent re-litigates. Full command set,

package/skills/odla/references/build.md

@@ -101,13 +101,14 @@ helpers (`computeBookableSlots`, formatters), never the admin key.
 
 Install the passive harness and scan before any production secret or deploy:
 
-Before installing the exact release, first verify
-`npm view @odla-ai/security@0.3.1 version`. An exact-version `E404` means the
-release is unavailable and blocks this preflight; it is not a clean scan and
-does not prove the package name is absent.
+First verify `npm view @odla-ai/security version`. A registry failure blocks
+this preflight; it is not a clean scan. Use a normal dependency declaration
+while ODLA is under active development, commit the lockfile, and record the
+resolved version with the scan evidence.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.3.1
+npm i -D @odla-ai/security
+npm ls @odla-ai/security
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 

package/skills/odla/references/pm.md

@@ -11,8 +11,8 @@ only mention in chat is a bug nobody fixes.
 ## What it is, mechanically
 
 - PM data lives on the **platform**, in odla's own shared store — *not* in the
-  app's database. There is nothing to install, schema, or provision, and no
-  entry in `odla.config.mjs`.
+  app's database. There is no PM schema or integration to install, but the
+  project app must already be registered so ownership can scope access.
 - Every item is tagged with an **appId**, and access rides **app co-ownership**:
   you see and write PM items for exactly the apps you co-own
   (`references/co-owners.md`). Co-own three apps and one `pm bug list` spans all
@@ -24,6 +24,12 @@ only mention in chat is a bug nobody fixes.
   app's **Project** tab in Studio): the board is drag-and-drop there, and every
   section filters by project.
 
+For a brand-new app, use a focused branch/commit and a clear checkpoint handoff
+only until the first successful `provision` registers it. Then initialize PM
+immediately and backfill the approved early decisions and evidence. Never use
+an unrelated app as a temporary PM bucket, and never keep a parallel project
+diary after PM is available.
+
 ## The four things, and when each one is right
 
 | You have | File it as | Because |
@@ -82,8 +88,16 @@ npx @odla-ai/cli pm task list --app <appId> --column doing
 ```
 
 then `pm bug list --app <appId> --status open` and
-`pm decision list --app <appId> --limit 10`. That is the state of the project in
-three commands — including anything a *different* agent left behind.
+`pm decision list --app <appId> --limit 10`, plus
+`pm goal list --app <appId> --status open`. Read the active task, linked goal,
+and their comments. That is the state of the project—including anything a
+*different* agent left behind.
+
+When coordinating several efforts, begin without `--app` to see doing tasks and
+open bugs across every co-owned project, then scope each write to the exact
+`appId` from that project's `odla.config.mjs`. Parallel agents should own
+different board tasks and different branches/worktrees; they coordinate through
+goal links and comments rather than sharing a working tree or status document.
 
 **While you build:**
 

package/skills/odla/references/sdks.md

@@ -137,13 +137,13 @@ in sync.
 Run the passive CLI in local/CI development; do not import it into the running
 Worker:
 
-Before installing the exact release, require
-`npm view @odla-ai/security@0.3.1 version` to succeed before installing it. An
-exact-version `E404` means the release is unavailable, not that the preflight
-passed, and does not prove the package name is absent.
+Require `npm view @odla-ai/security version` to succeed before installing it.
+A registry failure blocks the preflight; it is not a clean scan. Use a normal
+dependency declaration, commit the lockfile, and record the resolved version.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.3.1
+npm i -D @odla-ai/security
+npm ls @odla-ai/security
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 

package/skills/odla-migrate/SKILL.md

@@ -6,6 +6,7 @@ description: >
   move a static or GitHub Pages site to Cloudflare/odla, or to add a backend,
   database, login/auth, or AI features to a static site via odla.
 runbookOrder:
+  - references/project-state.md
   - references/phase-0-preflight.md
   - references/phase-1-static.md
   - references/phase-2-db.md
@@ -60,6 +61,9 @@ installed skill at `../odla/SKILL.md` instead.
    endpoints. An old public embed link is not a booking flow; preserve it via
    `bookingPageUrl` only until the native flow is verified. Google OAuth
    tokens never enter the repo, CLI, or chat.
+8. Project state belongs in odla PM, not a migration diary in the source tree.
+   Read `references/project-state.md` before recording or resuming work. Never
+   put credentials or secret values in PM.
 
 ## Phase state machine
 
@@ -68,10 +72,11 @@ Phases run strictly in order; each has a verification gate:
   P0 preflight -> P1 static-on-cloudflare -> P2 database -> P2b calendar (optional) -> P3 login
   -> P4 ai (optional) -> P5 prod + DNS cutover
 
-`MIGRATION.md` at the user's repo root is the durable state: create it in
-Phase 0, update it at every gate (phase, what changed, what was verified).
-In a fresh session, read MIGRATION.md first and resume from the recorded
-phase; `npx @odla-ai/cli doctor` confirms the current config state.
+PM is the durable state: goals define the migration gates, board tasks show the
+active phase, decisions preserve product and architecture choices, bugs capture
+defects, and comments carry evidence. In a fresh session, query PM first as
+specified in `references/project-state.md`; `npx @odla-ai/cli doctor` then
+confirms the checked-in config state.
 
 ## Auth model (one line)
 
@@ -116,6 +121,7 @@ so this is a natural first step.
 Read the current phase's file when you enter it — not before:
 
 - references/phase-0-preflight.md
+- references/project-state.md (read before Phase 0 and at every session start)
 - references/phase-1-static.md
 - references/phase-2-db.md
 - references/phase-2b-calendar.md (optional: live Google Calendar booking — slots, create/reschedule/cancel through the app's own Worker)

package/skills/odla-migrate/references/phase-0-preflight.md

@@ -31,16 +31,19 @@ Human obligation: none.
    `sk_live_`, `whsec_`, `ghp_`, `github_pat_`, `AKIA`, `-----BEGIN`).
    Any hit: STOP, show the human file:line (never the value), and
    resolve before continuing.
-5. Create `MIGRATION.md` at the repo root: the six-phase checklist with
-   P0 marked in progress, the inventory findings, and the chosen build
-   dir. Commit it (review `git status` first).
+5. Choose the intended stable odla `appId`. Follow
+   `project-state.md`'s pre-registration bootstrap: keep the inventory and
+   evidence in focused source-controlled artifacts/commits and the checkpoint
+   handoff. Do not create a parallel migration diary. PM becomes authoritative
+   immediately after Phase 2 registers the app.
 
 ## Verification checklist
 
 - [ ] Build runs clean and populates only the dedicated output dir
 - [ ] Output dir contains index.html and the site's assets
 - [ ] No committed secrets found (or resolved with the human)
-- [ ] MIGRATION.md committed
+- [ ] Intended `appId`, inventory evidence, and source commit recorded in the
+      checkpoint handoff
 
 Rollback: nothing to roll back.
 

package/skills/odla-migrate/references/phase-1-static.md

@@ -34,7 +34,9 @@ in this session).
 7. Add non-`deploy` npm scripts so CI never auto-deploys:
    `"deploy:app:dev": "<build> && wrangler deploy --env dev"` (and later
    `"deploy:app"` for prod). Never name a script exactly `deploy`.
-8. Record the workers.dev URL and parity results in MIGRATION.md.
+8. Record the workers.dev URL, immutable deployment version, and parity
+   evidence in the focused Phase 1 commit/checkpoint. Backfill that evidence
+   into PM immediately after Phase 2 registers the app.
 
 ## Verification checklist
 

package/skills/odla-migrate/references/phase-2-chapter.md

@@ -77,6 +77,12 @@ These bite silently; no smoke test catches them.
   `crm_record` mirrors identity, stage, billing, and Clerk linkage. Leader →
   follower delivery intentionally copies allowlisted record fields only, not
   another site's pipeline/account/billing authority.
+- **Leader/follower identity and credentials.** Each website has its own
+  `appId`, ODLA tenant/key, Clerk application/issuer, roles, and users. A leader
+  browser JWT authenticates only to the leader admin route. The leader Worker
+  sends a per-edge vault share secret; the follower validates it and writes
+  through its own `ODLA_API_KEY`. Never share a Clerk application between
+  websites, accept another site's JWT, or move either ODLA key across the edge.
 - **Route contracts.** Chapter owns `/api/config` and the group-scoped
   `/api/join-config`, but a matching path or matching monetary values do not
   make it a drop-in replacement. Compare method, auth, request body, response
@@ -91,6 +97,12 @@ These bite silently; no smoke test catches them.
   CRM does not declare that type and fields. Add the type to the follower config
   and expose it through the standard console before enabling the target in the
   leader.
+- **People workspace width.** The standard CRM list uses the full workspace
+  width until a record is selected, then becomes master/detail. Keep
+  `collectionSection({ collapseClosedDetail: true })` unless the empty detail
+  pane contains intentional useful content. `renderMaster` and `renderSummary`
+  customize content, not pane geometry. At 1280/1440 prove a wide table is not
+  squeezed into a narrow rail beside an empty pane.
 
 ## Install notes
 

package/skills/odla-migrate/references/phase-2-db.md

@@ -11,8 +11,11 @@ opens the review page in interactive terminals; loading it alone is inert.
 
 ## Steps
 
-1. Require `npm view @odla-ai/cli@0.16.6 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.16.6` and `npm i @odla-ai/db`.
+1. Require `npm view @odla-ai/cli version` to succeed, then run
+   `npm i -D @odla-ai/cli` and `npm i @odla-ai/db`. Use normal dependency
+   declarations while ODLA is under active development, commit the lockfile,
+   and record the resolved graph from
+   `npm ls @odla-ai/cli @odla-ai/db` in PM.
 2. `npx @odla-ai/cli init --app-id <id> --name "<Name>" --env dev --services db`
    Review `odla.config.mjs`. Keep `envs: ["dev"]` — prod is Phase 5. Set
    `links.dev` to the URL the Phase 1 `wrangler deploy` **actually printed** —
@@ -50,6 +53,10 @@ opens the review page in interactive terminals; loading it alone is inert.
    init — confirm with `git status`. Use
    `npx @odla-ai/cli secrets push --env dev` only to retry the secret-transfer
    portion (details and manual fallback: references/secrets-map.md).
+8. The app now exists. Before further implementation, follow
+   `project-state.md`: create the migration goals/tasks/decisions in PM,
+   backfill the approved Phase 0/1 evidence, and read the resulting active
+   task/goal before continuing.
 9. Add to `wrangler.jsonc` `env.dev.vars`: `ODLA_ENDPOINT`
    ("https://db.odla.ai"), `ODLA_TENANT` ("<appId>--dev"),
    `ODLA_PLATFORM` ("https://odla.ai"), `ODLA_APP_ID`, `ODLA_ENV`
@@ -70,7 +77,8 @@ opens the review page in interactive terminals; loading it alone is inert.
 - [ ] Routes work locally and on the deployed dev worker
 - [ ] `links.dev` set — public-config carries the URL and Studio shows it
 - [ ] `git status` shows no credential files staged
-- [ ] MIGRATION.md updated with tenant id + route list
+- [ ] PM initialized and Phase 0/1 evidence backfilled; Phase 2 route/tenant
+      evidence attached to the active task without credentials
 
 Rollback: the dev tenant is disposable; the live site never depended on
 it. Pages untouched.

package/skills/odla-migrate/references/phase-2b-calendar.md

@@ -16,10 +16,10 @@ routes are **server-side only** — they authenticate with the app's full
 this app's own Worker endpoints and may import pure helpers from
 `@odla-ai/calendar/client`.
 
-1. Require `npm view @odla-ai/calendar@0.2.0 version` to succeed, then
-   install `npm i --save-exact @odla-ai/calendar@0.2.0` as a runtime
-   dependency. An exact-version `E404` blocks this phase; do not substitute a
-   git checkout or another version.
+1. Require `npm view @odla-ai/calendar version` to succeed, then install
+   `npm i @odla-ai/calendar` as a runtime dependency. Use the normal dependency
+   range, commit the lockfile, and record `npm ls @odla-ai/calendar` in PM. A
+   registry failure blocks this phase; do not substitute a git checkout.
 2. Add `"calendar"` beside `"db"` in services and author the config block —
    booking rides the existing db key, so calendar adds no new secret:
 
@@ -127,4 +127,5 @@ same idempotency key returns `duplicate: true` (no second event); a taken
 slot returns 409 and the UI refetches slots; reschedule and cancel work via
 the stored `eventId`; zero attendee data is persisted anywhere except the
 app's own tenant record; no Google credential exists in local files; and
-`MIGRATION.md` records the booking-flow decision.
+PM records the booking-flow decision and the active task comment links this
+evidence.

package/skills/odla-migrate/references/phase-3-auth.md

@@ -22,6 +22,12 @@ doc — `https://clerk.com/docs/cli.md` — and prefer its syntax over the liter
 flags below. The steps here are the odla-shaped sequence; the live doc is
 authoritative for commands and flags.
 
+The development and production instances below belong to this one website's
+Clerk application. A separate leader or follower website uses its own Clerk
+application, issuer, publishable keys, roles, and users. Cross-site Chapter
+record delivery uses a per-edge vault share secret and the follower's own ODLA
+key; it never forwards or accepts another site's Clerk JWT.
+
 ## Steps
 
 1. Provision the Clerk app with the CLI (after the human's `clerk auth
@@ -67,6 +73,13 @@ authoritative for commands and flags.
    and attach `Clerk.session.getToken()` as the `Bearer` on `/api/*` calls.
 6. Deploy dev (`npm run deploy:app:dev`).
 
+Record and test the complete auth matrix: signed out, allowed, forbidden,
+malformed, expired, wrong issuer, role ladder, and sign-out/return routing. If
+the legacy verifier intentionally enforced `aud` or `azp`, preserve it with a
+host verifier and add negative fixtures until the replacement has the same
+policy. If it never enforced them, record those two cases as `n/a`; that is
+inherited policy scope, not proof that the rest of authorization is correct.
+
 Clerk is the **source of truth** for identity; odla-db keeps a mirror in
 `$users`. Shipping login (this phase) is enough to gate routes. Mirroring
 users into `$users` (svix webhook, "full" mode) is a **separate, optional
@@ -138,7 +151,8 @@ works. Before writing any markup:
       palette, logo, spacing) — human-confirmed, not self-asserted
 - [ ] Post-login redirect lands on a real URL (mind trailing-slash /
       directory-index routing), not a 404
-- [ ] MIGRATION.md updated (gated routes, Clerk instance name)
+- [ ] PM records the gated routes, this site's Clerk app/instance decision,
+      source commit, and deployed verification evidence
 
 Rollback: remove the auth layer / ungate the route; nothing outside dev
 changed.

package/skills/odla-migrate/references/phase-4-ai.md

@@ -36,7 +36,8 @@ own terminal so you never see the value.
 - [ ] The AI route returns a model response on the deployed dev worker
 - [ ] `wrangler.jsonc` `vars` contain NO provider key; `git grep` for the
       key's prefix finds nothing
-- [ ] MIGRATION.md updated (provider, model, route)
+- [ ] PM records the non-secret provider/model/route decision and deployed
+      verification evidence
 
 Rollback: remove the route; the vault key can be rotated/removed in
 Studio.

package/skills/odla-migrate/references/phase-5-cutover.md

@@ -24,10 +24,10 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    `secrets push --env prod --yes` only to retry the transfer (see
    references/secrets-map.md).
 3. Build, then run the passive pre-cutover security gate:
-   first require `npm view @odla-ai/security@0.3.1 version` to succeed. An
-   exact-version `E404` means the release is unavailable and blocks cutover;
-   it is not a clean scan and does not prove the package name is absent. Run
-   `npm i -D --save-exact @odla-ai/security@0.3.1` followed by
+   first require `npm view @odla-ai/security version` to succeed. A registry
+   failure blocks cutover; it is not a clean scan. Run
+   `npm i -D @odla-ai/security`, commit the lockfile, record the resolved
+   version from `npm ls @odla-ai/security`, then run
    `npx odla-security scan . --profile odla --out .odla/security/pre-cutover --fail-on high --fail-on-candidates critical`.
    Review `REPORT.md`; a candidate is a lead, not confirmation, and a baseline
    requires a concrete reason, owner, and expiry.
@@ -56,8 +56,9 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    in and out), `/api/*` routes, the AI route if present. Use a unique
    non-secret query value and capture cache/version headers so an earlier
    edge-cached response cannot masquerade as the deployed build.
-9. Update MIGRATION.md: cutover timestamp, verification results, and a
-   dated reminder ≥ 72 hours out to decommission Pages.
+9. Comment on the PM cutover task with the timestamp, immutable deployment
+   version, verification results, rollback checkpoint, and a dated follow-up
+   task ≥ 72 hours out to decommission Pages.
 10. After ≥ 72 hours of clean parallel-run and explicit human
     confirmation: disable GitHub Pages in the repo settings. KEEP the
     repo — it is still the source of the site.
@@ -90,6 +91,7 @@ production on the *existing* app. Then:
 Rollback: point DNS back at GitHub Pages (minutes). Nothing on the
 odla/Cloudflare side needs to be torn down to roll back.
 
-Done when: the 72-hour confirmation is done and MIGRATION.md is closed
-out. Congratulate the human — and mention Studio (https://odla.ai/studio) as
-where they watch their app from now on.
+Done when: the 72-hour confirmation is done, every migration conformance goal
+is met, and the remaining PM tasks are completed or explicitly deferred.
+Congratulate the human — and mention Studio (https://odla.ai/studio) as where
+they watch their app and PM state from now on.

package/skills/odla-migrate/references/project-state.md

@@ -0,0 +1,80 @@
+# Project state — use PM, not a migration diary
+
+The migration's durable coordination state lives in odla PM. Do not create or
+maintain a parallel migration/status diary in the source tree. Source files
+describe the product; PM describes goals, active work,
+decisions, defects, and verification evidence across agents and sessions.
+
+## Bootstrap before the odla app exists
+
+PM items require a registered, co-owned app. Phase 0 and Phase 1 deliberately
+precede platform registration, so do not pretend PM is available yet and do not
+borrow an unrelated app as a container.
+
+1. Choose the intended stable `appId` during Phase 0.
+2. Keep each early phase in a focused branch/commit. Put the phase, immutable
+   source commit, evidence locations, and next gate in the checkpoint handoff
+   and commit message. Do not create a diary file.
+3. A fresh agent before registration reruns the Phase 0 inventory checks, reads
+   the focused commits, and treats old branches, git history, unrelated
+   deployments, and prior experiments only as leads to verify.
+4. Immediately after the first successful Phase 2 `provision` registers the
+   app, initialize PM and backfill the approved Phase 0/1 outcomes and evidence.
+   From then on, PM is authoritative.
+
+This bootstrap gap ends at registration. Do not keep using commit messages as
+project management after PM becomes available.
+
+## Initialize the migration in PM
+
+Read the complete PM command contract at
+`../../odla/references/pm.md`. Never put a credential or secret in an item or
+comment.
+
+Create:
+
+- one conformance goal per acceptance outcome, with a concrete proof path or
+  command;
+- one task per migration track or phase, linked to its goal and placed in the
+  correct board column;
+- a decision for each product, data-authority, identity, route-contract, or
+  rollback choice;
+- a bug for every observed defect, including defects outside the current task.
+
+Backfill Phase 0/1 as completed tasks with comments naming the reviewed source
+commit, immutable deployment version where applicable, evidence artifact, and
+human checkpoint. Do not copy secrets or large logs into PM.
+
+## Start every later session by reading
+
+Resolve `appId` from `odla.config.mjs`; do not guess it from a repository name,
+deployment, old branch, or conversation.
+
+```cmd
+npx @odla-ai/cli pm task list --app <appId> --column doing
+npx @odla-ai/cli pm bug list --app <appId> --status open
+npx @odla-ai/cli pm decision list --app <appId> --limit 20
+npx @odla-ai/cli pm goal list --app <appId> --status open
+```
+
+Read the linked goal and the active task's comments before editing. Confirm
+their source commit/deployment evidence still identifies the implementation
+being tested. If PM and the working tree disagree, stop, investigate, and
+record the resolution as a decision or comment; do not silently pick whichever
+is more convenient.
+
+## Update at every gate
+
+- Move the phase/track task when work starts.
+- Comment with the exact verification command, result, source commit, candidate
+  deployment version, and rollback checkpoint.
+- Record an intentional contract or product delta as a decision.
+- File a defect as a bug rather than hiding it in a task comment.
+- Mark a goal met only after its stated proof passes.
+- Mark a task done only after its goal/evidence and human checkpoint are
+  complete.
+
+For parallel migrations, keep separate tasks per track (runtime, data, auth,
+payments, scheduling, email, public UI, admin UI, observability) and link each
+to its own conformance goal. This lets multiple agents claim independent work
+without sharing a branch or overwriting one status document.