From 18fe7adf10373535d5b002c0e00030ad89b63bd1 Mon Sep 17 00:00:00 2001 From: Destin Date: Mon, 28 Sep 2026 00:26:29 -0700 Subject: [PATCH] docs(workspace): align release and task-routing guidance Submitted via YouCoded Assistant --- .claude/commands/audit.md | 4 +-- .claude/rules/youcoded-toolkit.md | 49 +++---------------------------- .claude/skills/wrap-up/SKILL.md | 38 ++++++++++-------------- CLAUDE.md | 2 +- ROADMAP.md | 2 +- docs/MAP.md | 4 +-- docs/PITFALLS.md | 4 +-- docs/build-and-release.md | 24 +++++---------- docs/roadmap/dev-workspace.md | 9 ++++-- docs/workspace-workflows.md | 15 ++++++++++ docs/wrap-ups.md | 7 +++++ 11 files changed, 65 insertions(+), 93 deletions(-) diff --git a/.claude/commands/audit.md b/.claude/commands/audit.md index 1416b875c..211361d19 100644 --- a/.claude/commands/audit.md +++ b/.claude/commands/audit.md @@ -29,9 +29,9 @@ the claims live in the documents themselves and are harvested at run time. (The ## Process -### 0. Sync +### 0. Isolate and orient -Run `bash setup.sh` from the workspace root. Stale git state invalidates findings. +Run `node scripts/workspace-start.mjs --session [needed-component-repos…]` before edits; use the returned workspace and component worktrees, read its reorientation report and changed guidance. `bash setup.sh` is installation/explicit maintenance, not session startup. If an anchor needs a component that is absent, request that component with the same session key or report it as unverified; never turn a missing checkout into a false drift finding. A read-only request is not permission to run this fix-executing command. ### 1. Mechanical pass (always full, always first) diff --git a/.claude/rules/youcoded-toolkit.md b/.claude/rules/youcoded-toolkit.md index 29a8f2f87..0c1ff9830 100644 --- a/.claude/rules/youcoded-toolkit.md +++ b/.claude/rules/youcoded-toolkit.md @@ -4,7 +4,7 @@ paths: # root, never inside a session worktree — same bug as registries.md. See # .claude/rules/README.md. - "**/youcoded-core/**" -last_verified: 2026-07-15 +last_verified: 2026-09-27 verify: - path: youcoded-core/plugin.json - path: youcoded-core/hooks/hooks-manifest.json @@ -12,49 +12,8 @@ verify: - path: youcoded-core/hooks/worktree-guard.sh --- -# youcoded-core Plugin Rules +# Archived youcoded-core — read-only historical reference -You are editing the `youcoded-core` Claude Code plugin — a BUNDLED first-party plugin (alongside `wecoded-themes-plugin` + `wecoded-marketplace-publisher`), NOT a separate toolkit layer. Read workspace `docs/toolkit-structure.md` for full context. +**The GitHub repository was archived 2026-09-20.** Do not edit, version, tag, release, or push this repository. Its clone is retained for historical inspection and for older v1.2.4 installations; it is not a release target. A release or hook fix belongs in the app's bundled copies (`youcoded/desktop/hook-scripts/` and `youcoded/app/src/main/assets/`), which the app's tests pin to each other. Never change the running app's installed hooks or `~/.claude/settings.json` as a workaround. -## Status - -**Being deprecated.** `docs/active/plans/2026-04-21-deprecate-youcoded-core.md` is the active deprecation plan — `write-guard.sh` is moving into the app natively, and the repo will eventually be archived. Prefer fixing bugs over adding features here. New functionality belongs in the app or in a separate marketplace plugin. - -## Structure - -Single plugin with one manifest at the root: `youcoded-core/plugin.json` (currently v1.2.1). Phase 3 flattened the former three-layer decomposition — there is no `core/`, `life/`, or `productivity/` subdirectory. - -Top-level directories: -- `hooks/` — `hooks-manifest.json` + hook shell scripts -- `skills/` — only `setup-wizard/` and `remote-setup/` remain in-plugin -- `commands/` — `/update`, `/health`, `/diagnose` -- `bootstrap/` — historical manual-install script -- `scripts/` — post-update, migrations, security sweep - -Other skills (journal, encyclopedia, task inbox, theme-builder, skill-creator, google services) moved out during Phase 3 and now ship as independent marketplace plugins. - -## Hard rules - -- **Never edit hooks in `~/.claude/settings.json` directly.** Update `youcoded-core/hooks/hooks-manifest.json` — the desktop app's `HookReconciler` merges it in on launch. Direct edits get overwritten. -- **`.sh` files MUST have execute bit set.** Git on Windows doesn't set this automatically. After creating or renaming a script: `git update-index --chmod=+x path/to/file.sh`. Missing execute bit is the #1 cause of "hook does nothing" bugs. -- **`config.json` is portable; `config.local.json` is machine-specific.** `config.local.json` is rebuilt every session by `session-start.sh` — don't commit or sync it. -- **Feature work uses `git worktree add`**, not branch creation in the main plugin dir. `worktree-guard.sh` blocks branch switches here. - -## Skills - -Directories with `SKILL.md` files. YAML frontmatter `description` is how Claude discovers them. Be specific and concrete in descriptions — they're always in context. - -Currently in-plugin: -- `skills/setup-wizard/` — conversational first-run helper -- `skills/remote-setup/` — remote-access pairing flow - -## Hooks - -Declared in `youcoded-core/hooks/hooks-manifest.json`. Five hooks across three types. Guards to know about: -- `write-guard.sh` — PreToolUse, blocks writes when another session recently modified the file (being absorbed into the app natively per the deprecation plan) -- `worktree-guard.sh` — PreToolUse for Bash, blocks branch switches in the plugin dir -- `session-start.sh` — runs at session start, injects encyclopedia context, runs version migrations - -## Version bumping - -Bump `plugin.json` `version` on master. `.github/workflows/auto-tag.yml` detects the change vs `HEAD~1` and creates a `vX.Y.Z` tag automatically. +Why this rule is still path-scoped here: opening archived files for reference should not turn an old instruction into authorization to write them. See `docs/active/plans/2026-04-21-deprecate-youcoded-core.md` for remaining app-side retirement and `youcoded-admin/skills/release/SKILL.md` for the current app-only release. diff --git a/.claude/skills/wrap-up/SKILL.md b/.claude/skills/wrap-up/SKILL.md index b0e0ec179..44e319c3d 100644 --- a/.claude/skills/wrap-up/SKILL.md +++ b/.claude/skills/wrap-up/SKILL.md @@ -1,6 +1,6 @@ --- name: wrap-up -description: End-of-session workspace retrospective — replay what this session actually did (context loaded, searches forced by missing docs, tooling used, wrong turns, what Destin said he wants), turn that friction into durable workspace improvements, then push and ask about merging. Use whenever Destin says "wrap up", "wrap this up", "close out this session", "let's finish up", "we're done", "anything to improve?", or asks what this session taught us about the workspace. Every finding ends the session applied, filed as a dated roadmap entry, or explicitly dropped. +description: Use when Destin says "wrap up", "wrap this up", "close out this session", "let's finish up", "we're done", "anything to improve?", or asks what this session taught us about the workspace. --- # /wrap-up — turn this session into a better workspace @@ -9,12 +9,14 @@ A session is the only thing that knows where the workspace failed it; once the t closes, that knowledge is gone. Two prior retrospectives proved the failure mode: findings written down, never closed, rediscovered twice. -**This is a PROCESS, not a report generator.** Every recommendation ends this session -**applied**, **a dated roadmap entry** (`docs/roadmap/.md` — `ROADMAP.md` → "Filing -an item"), or **dropped with a reason**. +**This is a PROCESS, not a report generator.** Within an authorized editing session, +every recommendation ends **applied**, **a dated roadmap entry** (`docs/roadmap/.md` +— `ROADMAP.md` → "Filing an item"), or **dropped with a reason**. For a read-only session, +report the recommendation and ask before recording or applying it; wrap-up does not widen +what Destin authorized. -Retrospective first, while the session is fresh. Pushing and closing out (Step 6) is a -checklist that survives a tired session; honest self-replay is not. +Retrospective first, while the session is fresh. Branch-state reporting and close-out +(Step 6) are a checklist that survives a tired session; honest self-replay is not. ## What "better" means here @@ -100,7 +102,7 @@ poisons the ones that matter. A short session can end here. ## Step 5 — land them, on the session's branch -Retrospective edits ship WITH the work, so everything pushes and merges together: +When edits are authorized, retrospective changes stay on the same session branches as the work; neither this step nor wrap-up itself authorizes a push or merge: - Sub-repo edits (a pinning test, an ast-grep rule, a WHY comment) → the session's feature branch in that repo. @@ -117,15 +119,11 @@ Then: - **Roadmap:** the area file whose `Filing test:` says yes; **dedupe by file or symbol name, not by symptom** — searching `flaky` instead of `sync-spaces-engine` filed a duplicate. - **Dropped:** say so in your reply, with the reason. An unrecorded rejection gets re-argued. -- **Always:** append this session's entry to `docs/wrap-ups.md` — its header explains the - format. That file is Step 1 for the next session; skipping it is how the same friction - gets rediscovered. +- **When editing is authorized:** append this session's entry to `docs/wrap-ups.md` — its header explains the format. In a read-only session, give the retrospective in chat and ask before recording it. The ledger is Step 1 for the next editing session. -## Step 6 — push everything, then ask about merging +## Step 6 — identify local-only work and report the boundary -**Push every branch this session touched. Do not ask.** A push is a backup, not a release: -it ships nothing, and `git push -d` undoes it. An unpushed branch is the only state where -work can actually be lost. +**Inspect this session's branches; publish only within the authorization for this task.** A push backs up commits but also publishes them to the remote, and a later branch deletion does not erase copies others fetched. If Destin asked to push, verify the branch and scan public-repo commits for secrets first. Otherwise report the commits that exist only on this machine; do not silently push them. A read-only session must not become an editing or shipping session because it is ending. Then sweep for anything else local-only — other sessions leave branches behind, and one sweep found seven across four repos: @@ -164,8 +162,7 @@ done For a fuller inventory across every OLD worktree, not just this session's own, `node scripts/prune-worktrees.mjs` reports which are actually safe to delete (clean, merged, unused) — dry run only; never run its `--apply` without Destin naming the exact ones. -**Secrets-scan any branch before its first push to a PUBLIC repo — including swept ones you -never read.** `youcoded` and `youcoded-dev` are public; `youcoded-admin` is not. +**Secrets-scan any branch before its first authorized push to a PUBLIC repo.** For other sessions' branches, report local-only work rather than publishing it under this session's authority. `youcoded` and `youcoded-dev` are public; `youcoded-admin` is not. Then run the close-out check per branch — read-only, always exits 0, and it detects whether the branch landed and checks accordingly: @@ -174,17 +171,14 @@ the branch landed and checks accordingly: bash scripts/close-out.sh [] # repo: a sub-repo name, or `workspace` ``` -**Finish every line it reports.** A `TODO` is yours to do now. A `--` line is a judgement it -deliberately refuses to make — make it: close the roadmap item **if the work actually +**Address every line within the authorized scope; report the rest.** A `TODO` is not permission to edit or ship beyond the task. A `--` line is a judgement it +deliberately refuses to make — make it only with evidence: close the roadmap item **if the work actually shipped** (`node scripts/roadmap-check.mjs --close : --ref ""`, then archive its report); give the subsystem a `docs/MAP.md` row ("no rule" is an answer, "no row" is not); move `status: shipped` docs to `docs/archive/` and repoint cross-links — but a doc describing work still in review stays in `docs/active/`, or it goes invisible to the reviewing session. -**Then ask Destin one question: "Ready to merge?"** With a recommendation and, per branch, -what is actually proven — did `scripts/verify.sh` pass, has any of it run for real, what is -unverified. **Default to NOT merging** unless he says yes; he decides. Never end a turn -suggesting a merge (`CLAUDE.md` → iteration mode), and do not open a PR unless he asks. +**End with the state of each branch and what was actually proven** — did `scripts/verify.sh` pass, has any of it run for real, what is unverified or only saved locally. Do not propose a merge, open a PR, or merge as a routine wrap-up step. If Destin expressly asks whether to merge, present the evidence and wait for his instruction; merging and pushing require explicit authorization (`CLAUDE.md` → Git, worktrees, and shipping). **You run the commands, not Destin.** Never end a turn handing him something to type. diff --git a/CLAUDE.md b/CLAUDE.md index 32eabd2a7..1f60b57cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,7 +77,7 @@ Never invent an error cause. Use ``: specific accurate detail + Retr ## Development Workflow -Load only the procedure needed. Existing approval gates still apply; moving their recipes out of this file does not waive them. +Choose the route by request (read-only review, edit, UI feature, fix-executing audit, wrap-up, or release) in `docs/workspace-workflows.md` → Choosing a workflow. Load only the procedure needed. Existing approval gates still apply; moving their recipes out of this file does not waive them. ### New Features & UI/UX Changes diff --git a/ROADMAP.md b/ROADMAP.md index eb5949784..6aef7c273 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -71,7 +71,7 @@ Target: `v1.3.1` ## Backlogs | Area | Open | Needs verify | Decisions | Parked | |---|---|---|---|---| -| [dev-workspace](docs/roadmap/dev-workspace.md) — building the app, not the app | 101 | 32 | 4 | 9 | +| [dev-workspace](docs/roadmap/dev-workspace.md) — building the app, not the app | 101 | 31 | 4 | 9 | | [native-harness](docs/roadmap/native-harness.md) — the app's own agent doing work | 57 | 10 | 5 | 25 | | [user-interface](docs/roadmap/user-interface.md) — shared primitives, chrome, layout, copy | 40 | 16 | 2 | 6 | | [remote-access](docs/roadmap/remote-access.md) — reaching the app from another device | 30 | 7 | 1 | 4 | diff --git a/docs/MAP.md b/docs/MAP.md index 63796ce82..cb6ff5b66 100644 --- a/docs/MAP.md +++ b/docs/MAP.md @@ -75,8 +75,8 @@ Rules live in `.claude/rules/`; depth docs are read-on-demand (`youcoded/docs/`, | Marketplace worker | `wecoded-marketplace/worker/src/lib/analytics.ts`
`wecoded-marketplace/worker/src/lib/admin-filter.ts` | worker-backend | `wecoded-marketplace/docs/worker-backend.md` | `wecoded-marketplace/worker/test/analytics-lib.test.ts`
`wecoded-marketplace/worker/test/admin-filter.test.ts`
`wecoded-marketplace/.github/workflows/worker-ci.yml` (pre-merge typecheck+test) | | Marketplace catalog (serve + hourly ingest) | `wecoded-marketplace/worker/src/catalog/routes.ts`
`wecoded-marketplace/worker/src/catalog/publish.ts`
`wecoded-marketplace/worker/src/catalog/auth.ts`
`wecoded-marketplace/worker/migrations/0006_catalog.sql`
`wecoded-marketplace/scripts/catalog/build.mjs`
`wecoded-marketplace/scripts/catalog/lib/capabilities.mjs`
`wecoded-marketplace/scripts/catalog/sources/` (wecoded · docker · awesome-copilot · cursorrules)
`youcoded/desktop/src/main/skill-provider.ts` (`fetchIndex` reads it)
`youcoded/app/src/main/kotlin/com/youcoded/app/skills/MarketplaceFetcher.kt` | catalog
registries (client side) | `wecoded-marketplace/docs/catalog.md` | `wecoded-marketplace/worker/test/catalog.test.ts`
`wecoded-marketplace/worker/test/catalog-publish.test.ts`
`wecoded-marketplace/scripts/catalog/test/` (`node --test scripts/catalog/test/*.test.mjs`)
`youcoded/desktop/tests/skill-provider-catalog.test.ts`
`wecoded-marketplace/.github/workflows/catalog-ingest.yml` (hourly; red run IS the alarm) | | Claude Code hooks the app registers (`~/.claude/settings.json`) | `youcoded/desktop/src/main/hook-reconciler.ts` (adds required hooks, enforces MAX timeout, **prunes dead ones — ownership is decided by `listInstalledPluginDirs()`, which only walks dirs that EXIST**)
`youcoded/desktop/src/main/legacy-cleanup.ts` (deletes the retired `~/.claude/plugins/youcoded-core/` clone at launch — deleting it is what makes its leftover entries look user-added, so the reconciler carries an owned-legacy-root list)
`youcoded/desktop/src/main/claude-code-registry.ts` (`listInstalledPluginDirs`)
`youcoded/desktop/src/main/hook-relay.ts` (the named pipe hooks talk back through — `HookOwnerGate` drops hooks from a `claude` nested inside a session, an ask for a session this app does not own is handed straight back undecided, and a held ask gets the app's 2 h hold; Android: `EventBridge.kt`, see the Claude Code prompts row)
`youcoded/desktop/scripts/install-hooks.js` (the app's OWN hooks — deliberately separate from the plugin reconciler)
`youcoded/desktop/src/main/claude-settings.ts` (**the ONE reader/writer of the file** — read once, compare before write under the lock; a corrupt file becomes a timestamped backup and a fresh file)
`youcoded/desktop/src/main/launch-settings-chores.ts` (the boot chores — reconcile, prompt-suggestion off, retention default — in one locked cycle)
`youcoded/app/src/main/kotlin/com/youcoded/app/runtime/Bootstrap.kt` (~L900 — Android's own prune; it drops the legacy prefix unconditionally, desktop only when the file is missing) | (no rule) | `docs/toolkit-structure.md` | `youcoded/desktop/tests/hook-reconciler-prune.test.ts`
`youcoded/desktop/tests/hook-relay.test.ts` (owner gate, pass-through, the hold)
`youcoded/desktop/tests/permission-timeout-margins.test.ts` (app 2 h < relay 2 h 30 m < Claude Code 3 h — never tidy them equal)
`youcoded/desktop/tests/legacy-cleanup.test.ts`
`youcoded/desktop/tests/claude-settings.test.ts`
`youcoded/desktop/tests/launch-settings-chores.test.ts` | -| youcoded-core plugin | `youcoded-core/hooks/hooks-manifest.json`
`youcoded-core/plugin.json` | youcoded-toolkit | `docs/toolkit-structure.md` | manual (hook runtime) | -| Build & release | `youcoded/app/build.gradle.kts`
`youcoded/scripts/build-web-ui.sh`
`youcoded/.github/workflows/desktop-test-build.yml` (beta builds)
`youcoded/desktop/src/shared/version-line.ts` | — | `docs/build-and-release.md` | `youcoded/.github/workflows/desktop-release.yml`
`youcoded/desktop/tests/version-line.test.ts` | +| Archived youcoded-core plugin (read-only history; not a release target) | `youcoded-core/hooks/hooks-manifest.json`
`youcoded-core/plugin.json` | youcoded-toolkit | `docs/toolkit-structure.md` (historical) | no new releases; app hook parity: `youcoded/desktop/tests/write-guard-contract.test.ts` | +| Build & release | `youcoded-admin/skills/release/SKILL.md` (app-only procedure)
`youcoded/app/build.gradle.kts`
`youcoded/scripts/build-web-ui.sh`
`youcoded/.github/workflows/desktop-test-build.yml` (beta builds)
`youcoded/desktop/src/shared/version-line.ts` | — | `docs/build-and-release.md` | `youcoded-admin/skills/release/release-skill.test.mjs`
`youcoded/.github/workflows/desktop-release.yml`
`youcoded/.github/workflows/android-release.yml`
`youcoded/desktop/tests/version-line.test.ts` | ## Hot paths — the exact file, without a search diff --git a/docs/PITFALLS.md b/docs/PITFALLS.md index 693f8bd0b..856414c39 100644 --- a/docs/PITFALLS.md +++ b/docs/PITFALLS.md @@ -9,8 +9,8 @@ This file now holds **only cross-repo invariants** — constraints that span two - **CI stamps the Android version: `versionName` from the tag or `.`, `versionCode` = `100 + run_number` of `android-release.yml`.** Hand-set values in the gradle file are local-only. *Why:* every beta shipped as `20 / 1.2.4`; a run counter is monotonic, as Play requires. *Guard:* `desktop/tests/android-honest-build.test.ts`. - **One `vX.Y.Z` tag on youcoded master ships all platforms.** It triggers both `android-release.yml` and `desktop-release.yml` → a single GitHub Release with APK/AAB + Win/Mac/Linux installers. *Why:* coordinated cross-platform release. *Guard:* CI workflows. - **Desktop version comes from the git tag, not `package.json`.** CI extracts the version from the tag and patches `package.json` during build. *Guard:* `desktop-release.yml`. -- **youcoded-core auto-tags on `plugin.json` version change** on master — `youcoded-core/.github/workflows/auto-tag.yml` compares `HEAD` vs `HEAD~1` and creates the tag. There is one manifest (no layer-level `plugin.json`). *Guard:* `auto-tag.yml`. -- **Multi-repo release coordination lives in the `youcoded-admin` release skill** (`youcoded-admin/skills/release/SKILL.md`) across the app, `youcoded-core`, and admin. See build order + flows in `docs/build-and-release.md`. History: v2.3.0 lessons (fragile auto-tag, untested hooks, protocol-parity blind spots) — memory `project_release_lessons_2_3_0`. +- **`youcoded-core` is archived and read-only, never a release target.** Hook fixes land in the app's bundled desktop/Android copies, not the old plugin. *Guard:* `youcoded/desktop/tests/write-guard-contract.test.ts` and `.claude/rules/youcoded-toolkit.md`. +- **App release coordination lives in the `youcoded-admin` release skill** (`youcoded-admin/skills/release/SKILL.md`). The app tag starts both platform workflows; admin owns the procedure and platform checklist, not a separate product release. See `docs/build-and-release.md`. *Guard:* `youcoded-admin/skills/release/release-skill.test.mjs` and platform CI workflows. ## IPC and cross-platform parity diff --git a/docs/build-and-release.md b/docs/build-and-release.md index 0433c284c..25dfa9089 100644 --- a/docs/build-and-release.md +++ b/docs/build-and-release.md @@ -23,22 +23,14 @@ A single `vX.Y.Z` tag in youcoded triggers both `android-release.yml` and `deskt ## Release flows ### App (Desktop + Android) -1. Bump `versionCode` + `versionName` in `youcoded/app/build.gradle.kts` -2. Regenerate the landing-page demos: `bash scripts/ui-review/site-assets.sh `, review `docs/gallery` + `docs/media`, commit them with the version bump — the site's loops and embed are built from the renderer and go stale otherwise. -3. Tag `vX.Y.Z` in youcoded on master -4. Both platform workflows trigger → single GitHub Release with all artifacts -5. Confirm `youcoded-release.json` and `youcoded-release.json.sig` are on the release — without them - the in-app Update button refuses the release. If `Sign release manifest` warned instead, sign by - hand: download every desktop installer from the release into one folder, then from `youcoded/` - run `node desktop/scripts/generate-release-manifest.mjs --dir --version vX.Y.Z --key - ~/system/youcoded-release-signing/update-signing-key.private.pem --verify-with - desktop/src/main/update-signing-key.ts` and `gh release upload vX.Y.Z /youcoded-release.json - /youcoded-release.json.sig`. - -### Toolkit (youcoded-core) -1. Bump `version` field in `youcoded-core/plugin.json` on master -2. `auto-tag.yml` compares `HEAD` vs `HEAD~1` plugin.json versions -3. If changed, creates `vX.Y.Z` tag automatically + +The release procedure is `youcoded-admin/skills/release/SKILL.md`: review the app diff and readiness, prepare an isolated candidate, review its PR and candidate-specific checks where authorized, then obtain Destin's explicit go/no-go **to merge, push master and tag**. Tag the verified result on remote master. A candidate branch push solely for CI requires its own permission and is not release approval; when candidate CI cannot run, disclose that at go/no-go. Never commit or tag in a shared checkout to stage a release. `youcoded-core` is archived; it has no release steps. + +1. Regenerate the landing-page demos with `bash scripts/ui-review/site-assets.sh `; inspect the gallery and media output and include approved files in the candidate. The site's loops and embed come from the renderer and otherwise go stale. +2. Review one app CHANGELOG entry and check the candidate on desktop and Android. The **tag**, not locally edited version files, sets the shipped version: desktop CI patches `package.json`; Android CI stamps `versionName` and a monotonic `versionCode`. Local Gradle values are not Play release values. +3. After candidate review, explicit release go/no-go, and the authorized merge/push, tag `vX.Y.Z` on the verified app commit on remote master. Its two workflows must both pass: desktop waits for every OS before upload; Android uploads APK/AAB. They contribute to one GitHub Release, but the tag push alone does not prove the release finished. +4. Check the actual release assets, including `youcoded-release.json` and `youcoded-release.json.sig` — without both the in-app Update button refuses the release even if installers uploaded. **Verify contents, not just names:** download all release installers and the manifest/signature into an empty temporary directory, confirm the manifest version and every installer's SHA-256/byte size match the downloaded files, and verify the signature against `desktop/src/main/update-signing-key.ts` (helpers exported by `desktop/scripts/generate-release-manifest.mjs`). If `Sign release manifest` warned, diagnose it and get approval for manual signing: use a NEW EMPTY folder containing ONLY installers downloaded from that exact release, then from `youcoded/` run `node desktop/scripts/generate-release-manifest.mjs --dir --version vX.Y.Z --key ~/system/youcoded-release-signing/update-signing-key.private.pem --verify-with desktop/src/main/update-signing-key.ts`. Inspect the newly generated manifest before upload. If the release already has either manifest file, check what is there first; use `gh release upload vX.Y.Z /youcoded-release.json /youcoded-release.json.sig --clobber` only after confirming an intentional replacement of the pair. Never mix installers from another release into the signing folder. +5. PartyKit deploys on a master push touching `desktop/partykit/**` (or explicit dispatch), not because a later release tag was pushed. Verify the actual relevant deployment run if game-server changes are part of the release. ### Worker (wecoded-marketplace) **The Cloudflare Worker auto-deploys on push to master — never tell Destin to run `wrangler deploy` manually.** `.github/workflows/worker-deploy.yml` runs on `push` to `master` (filtered to `worker/**` and the workflow file itself) plus `workflow_dispatch`. The job runs `npm ci` → `npm run typecheck` → `npm test` → `wrangler d1 migrations apply --remote` → `wrangler deploy` → `wrangler secret put` for every required secret. Cloudflare credentials live in repo secrets (`CF_API_TOKEN`, `CF_ACCOUNT_ID`); no local `wrangler login` needed. diff --git a/docs/roadmap/dev-workspace.md b/docs/roadmap/dev-workspace.md index 2b8b9b9d4..4fd349fc8 100644 --- a/docs/roadmap/dev-workspace.md +++ b/docs/roadmap/dev-workspace.md @@ -718,8 +718,13 @@ seen-on is always n/a here. `n/a` `confirmed` `checked 2026-09-18` - [ ] Close-out can say "the work landed" for a new branch whose edits are still uncommitted, - then recommend deleting its worktree; it should notice unfinished edits before declaring success - `n/a` `needs-verify` `checked 2026-09-05` + then recommend deleting its worktree; it should notice unfinished edits before declaring success. + Reproduced 2026-09-27 on `session/release-skill-current-flow-20260927` in both workspace + and `youcoded-admin`: the tip is just fetched master and the remote branch does not exist, + but both worktrees hold uncommitted edits. `close-out.sh` printed "the work landed", + "remote branch deleted" and TODOs to delete both worktrees. Those verdicts refer only to + the branch tip, not the unfinished files; do NOT follow those deletion suggestions. + `n/a` `confirmed` `checked 2026-09-27` - [ ] Recheck the old cleanup handoff's remaining unused-code and bug-hunt ideas before treating them as completed; its retired tooling instructions are no longer a safe starting point diff --git a/docs/workspace-workflows.md b/docs/workspace-workflows.md index 079cd109c..a80f9aa52 100644 --- a/docs/workspace-workflows.md +++ b/docs/workspace-workflows.md @@ -97,6 +97,21 @@ check, read its output, then merge; read the merge result, then clean up. A guar ## Development Workflow +### Choosing a workflow + +Choose by the action being requested, not by whether a skill happens to be installed: + +| Request | Route | +|---|---| +| Investigate, review, compare or recommend | Read-only findings. Do not run a fix-executing `/audit`, edit files or publish unless Destin also asked for changes. | +| Change code, docs or guidance | Start/resume an isolated session with `workspace-start`; read MAP's rule and guard for the affected area, then verify the changed branch. A correction to docs is still an edit. | +| Design a new YouCoded interface | Follow `.claude/rules/feature-flow.md`: questions and Workbench UI before backend, then approval through review decks. The short route for a clear small UI change requires Destin's agreement; it does not apply to read-only reviews or non-UI doc corrections. | +| Audit workspace guidance | `/audit` is fix-executing maintenance, not the read-only review above. Run it only when edits are authorized, in an isolated session; its command file owns the audit procedure. | +| Wrap up a session | Use `.claude/skills/wrap-up/SKILL.md` to review and account for this session's work. Wrap-up by itself authorizes neither publishing a branch nor merging; follow the explicit scope and report unfinished work. | +| Ship a release | Use `youcoded-admin/skills/release/SKILL.md` for the app release, subject to its own go/no-go. A request to review release readiness is not permission to tag or publish. | + +If a named skill cannot be invoked in the current runtime, read its repository `SKILL.md` or command instructions and follow the applicable procedure; if neither exists, report the missing procedure rather than improvising approval or shipping steps. **The root `CLAUDE.md` and live-app safety rule win over a conflicting skill or older recipe.** This table routes tasks; it does not grant permission to perform them. + Release builds happen through GitHub Actions CI in the relevant sub-repo. For iterating on desktop changes locally alongside Destin's installed/built app: ```bash diff --git a/docs/wrap-ups.md b/docs/wrap-ups.md index 6c178910b..bf606d101 100644 --- a/docs/wrap-ups.md +++ b/docs/wrap-ups.md @@ -793,3 +793,10 @@ recurred — the repetition is the data. - Destin: "ignore android" (scope), "investigate more thoroughly and fix… check our own work" → no new rule (global.md covers both); Android and phone findings filed (android audit appendix, `remote-access.md`), a split reply bubble filed in `chat-data.md` - The workspace hook suite failed 1/430 at close-out, on master too: `glob-guard.test.mjs` asserted `kill -9 4321 5678` is allowed, and pid 4321 was Destin's live app that day, so the live-app guard (correctly) blocked it → applied: every non-live-app case runs against an empty fake /proc (`GLOB_GUARD_PROC`); shown red against the real /proc - deleted/merged: App.tsx's first-page closure moved to `state/first-page-loader.ts` (App.tsx −27 lines, budget lowered to match) + +## 2026-09-27 — developer-tooling inventory, release procedure cleanup, abandoned Dev Desk (session/release-skill-current-flow-20260927) +- The release skill still carried writable youcoded-core steps despite its archived-repo warning, and versioned in shared checkouts before the go/no-go → applied on this session's uncommitted `youcoded-admin` branch: app-only release procedure, candidate-before-tag gates and release-skill contract test (7 passing); matching workspace MAP/release/rule references corrected. No release was run. +- Planning, read-only audit, wrap-up and shipping instructions sent assistants down conflicting routes; the old `/audit` still prescribed `setup.sh` and wrap-up demanded unsolicited pushes while also forbidding merge suggestions → applied on this session's uncommitted workspace branch: routing table, audit startup correction and scope-aware wrap-up. Anchor audit and 116 workspace tests passed. +- Destin rejected the Pages Dev Desk even after the earlier dashboard session had said a status board without direct actions was not useful; the current Pages model could not provide those actions, and copying prompts plus greyed controls was not a substitute → dropped: Destin asked to abandon it. The installed Page and its isolated worktree, test and handoff were removed after confirming no saved data or later edits. Do not resurrect this Page as a prompt menu; optional computer programs are already tracked under the existing Pages phasing plan. +- RECURRENCE: `close-out.sh` called both release-instruction branches "landed" and their absent remote branches "deleted", then suggested deleting the worktrees while both contain uncommitted work → roadmap: existing `docs/roadmap/dev-workspace.md` close-out item upgraded to confirmed with this reproduction; deletion refused. The tool checked commit ancestry, not whether the actual edits were saved. +- deleted/merged: the release procedure lost its retired two-repo path (816 lines to a short app-only guide); the abandoned Page and its scratch previews were removed. Nothing from this session was pushed, merged, tagged or deployed.