openplanr 1.25.3 → 2.0.0

package/docs/CROSS_RUNTIME_SETUP.md

@@ -0,0 +1,168 @@
+# Cross-runtime setup and operations
+
+## Install
+
+```bash
+curl -fsSL https://openplanr.dev/install.sh | sh
+# PowerShell
+irm https://openplanr.dev/install.ps1 | iex
+```
+
+The installer requires Node.js 20+ and never installs or upgrades Node silently.
+It installs the CLI without changing the current directory. Then change into a
+project and run guided setup:
+
+```bash
+cd my-project
+planr setup
+planr doctor
+```
+
+The full pipeline is the default. Use `planr setup --minimal` for dedicated
+planning only, or `npx openplanr@latest setup` without a global install.
+
+## Preview, apply, and migrate
+
+```bash
+planr setup --dry-run
+planr setup
+planr doctor
+```
+
+Guided setup detects Claude Code, Codex, and Cursor, explains unavailable shell
+commands, and prompts for the agents and scope to configure. User scope is the
+default. Cursor currently requires project scope. Project writes require a Git
+worktree or initialized `.planr` project; setup will never treat `$HOME` as a
+project automatically.
+
+Setup prints a compact change summary before mutation; use `--verbose` for
+every target. Existing files are copied byte-for-byte to
+`~/.planr/backups/` with hashes and a migration manifest. Only managed marker
+blocks are replaced; content outside those blocks is preserved.
+
+When Claude Code is selected at user scope, the same preview includes the
+official marketplace and plugin operations. Confirmed setup refreshes
+`openplanr/marketplace`, installs missing OpenPlanr plugins, and updates stale
+ones to the compatibility versions recorded by the CLI. This is intentionally
+not performed by the piped web installer. Restart Claude Code when setup says a
+plugin changed.
+
+For CI and provisioning, supply choices explicitly:
+
+```bash
+planr setup --runtime auto --scope user --yes
+planr setup --runtime codex --scope project --yes
+planr setup --runtime all --scope both --yes
+planr runtime update claude --scope user --yes
+```
+
+Repeated setup is idempotent. To restore the last pre-setup state:
+
+```bash
+planr runtime rollback
+```
+
+Installing or updating one adapter is additive: it keeps every other managed
+adapter and preserves each adapter's existing scope. For example, adding Codex
+at user scope does not widen an existing project-only Cursor installation.
+
+Full setup installs the portable planning and pipeline assets for the selected
+runtime. `planr doctor` reports managed-file drift and runtime availability
+without calling a provider.
+
+## Codex Operate bundle and first Cycle
+
+Full Codex setup installs every canonical, manifest-owned `planr-*` skill in the
+Protocol registry as one global user bundle. The Operate set is `planr-operate` plus
+the seven `planr-{ceo,cto,cpo,cmo,coo,challenger,chair}-review` executors. Every
+asset is digest-verified. Software remains a registered Operate domain, but no
+generic software executor skill is installed or advertised.
+
+Invoke `$planr-operate` directly for the guided local review. It uses sensible
+current-snapshot defaults, asks through the host's native question surface only
+for consequential ambiguity, and keeps missing lens output as a visible issue
+instead of blocking the rest of the report.
+
+The validator is optional editing help for any generated note:
+
+```bash
+planr operate validate-note <note.md> --profile advisor|challenger|chair|board-report --contract-version 2.0.0 --json
+```
+
+Omit `--contract-version` to auto-detect current v2 and historical v1 notes.
+
+The durable Operate runtime is separate. Discover its exact registered domain
+identity with `planr operate domains --json`; neither setup nor the runtime
+guesses a domain version. Its issued executors receive a prepared packet and use
+only:
+
+```bash
+planr operate assignment prepare <assignmentId> --actor <agentId> --runtime codex --json
+planr operate assignment validate <packetId> --content-file <resultPath|-> --json
+planr operate assignment submit <packetId> --content-file <resultPath|-> --json
+```
+
+The packet contains exact issued inputs, schema paths, evidence matrix, rubric,
+and an intentionally incomplete role template. Private state remains below
+`.planr/operate/` and is not an executor research surface.
+
+Removal deletes only recorded OpenPlanr-owned files whose hashes still match.
+Modified or unknown files produce `E_MIGRATION_CONFLICT` before any adapter
+bytes are removed. User-scope assets shared by multiple projects are
+reference-safe: removing or rolling back one project retains them until no
+other managed project installation depends on them.
+
+## Troubleshooting and upgrades
+
+```bash
+planr doctor --strict --json
+planr setup --dry-run
+planr upgrade status
+planr upgrade apply
+```
+
+- Missing or stale skills: inspect doctor output, then re-run `planr setup`.
+  Known owned bytes are repaired transactionally; unknown or modified files are
+  preserved and reported as `E_MIGRATION_CONFLICT`.
+- First Cycle rejects `--domain-version`: run `planr operate domains --json`
+  and copy the exact domain identity. Operate Protocol `2.0.0` is not a domain
+  version.
+- Assignment prepare/validate/submit fails: use the returned machine `code` and
+  `problem`. The CLI intentionally omits host paths and stacks; author only the
+  returned `resultPath` and keep `packetId` unchanged.
+- CLI/skill parity is incompatible: run `planr upgrade status`, then the
+  explicit `planr upgrade apply`, followed by `planr setup` and
+  `planr doctor --strict --json` again.
+
+## Offline, remote, and SSH use
+
+After npm packages and runtime assets are installed, planning artifacts,
+runtime routing, status, sync audit, dashboard, design boards, and doctor work
+without fetching OpenPlanr sources. Provider-backed generation still requires
+the selected provider or a local model runtime.
+
+On remote/SSH machines use `--scope user` for reusable skills and `--scope project`
+for repository policy. Forward a loopback port explicitly through SSH when a
+local artifact-review browser runs elsewhere.
+
+## Windows
+
+The PowerShell installer and CLI support Node 20/22 on Windows. Project paths in
+committed locks and generated rules are repository-relative. Machine-specific
+absolute paths remain in the user runtime state and backups.
+
+## Security
+
+- No telemetry is added.
+- Setup never installs Node or deletes unknown user files.
+- `doctor --fix` can remove legacy project files accidentally installed under
+  `$HOME`, but only when their recorded ownership hashes still match.
+- `doctor --fix` can remove unreachable design/dashboard daemon state after a
+  preview and second health check; it never kills or inspects unrelated processes.
+- `doctor` detects stale or malformed Claude plugins read-only. `doctor --fix`
+  does not install or update them; use the explicit runtime update command it
+  prints.
+- Credentials are not written to runtime locks or provenance.
+- Doctor redacts secrets and only fixes owned files after preview.
+- Provenance is append-only. Recovery requires an explicit event rather than
+  fabricated history.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,227 @@
+# Troubleshooting
+
+Common issues and how to resolve them.
+
+Start with the unified health check:
+
+```bash
+planr doctor --json
+planr setup --dry-run
+```
+
+`doctor --fix` previews owned generated-file repairs and stale Planr daemon
+state. It asks once, rechecks daemon health, and removes only Planr-owned state;
+it never kills a process. Package installation, version changes, provenance
+recovery, credential changes, and unrelated deletion remain explicit gates.
+
+An unavailable runtime is informational unless setup or the project lock
+actually selected it. A selected runtime that disappears remains a warning.
+
+## Runtime setup and migration
+
+- `E_NODE_VERSION`: install Node.js 20 or newer; the installer never changes Node.
+- `E_PROJECT_CONTEXT_REQUIRED`: change into a Git or initialized OpenPlanr
+  project before selecting project scope, or use `--scope user`.
+- `E_RUNTIME_AMBIGUOUS`: pass `--runtime` or set a project default.
+- `E_LOCK_INCOMPATIBLE`: run the exact `planr runtime update ...` command shown.
+- `E_MIGRATION_CONFLICT`: a managed file changed after setup; preview, preserve
+  the edit, or use `planr runtime rollback`.
+- `E_CLAUDE_PLUGIN_INSPECTION_FAILED`: update Claude Code so its plugin manager
+  is available, then rerun `planr setup --runtime claude --scope user`.
+- `E_CLAUDE_PLUGIN_UPDATE_FAILED`: verify GitHub/marketplace connectivity, run
+  `planr runtime update claude --scope user`, and restart Claude Code.
+- `E_PROVENANCE_WRITE`: repair permissions, then append an explicit recovery
+  event; doctor never invents history silently.
+
+If doctor reports `runtime-claude-plugins`, the installed plugin version or
+manifest identity does not match the compatible release. Run:
+
+```bash
+planr runtime update claude --scope user
+```
+
+Review and confirm the listed marketplace/plugin operations, then restart
+Claude Code. A legacy `openplanr@openplanr-skills` installation is reported
+separately and is never silently removed; verify `openplanr@openplanr` first,
+then remove the legacy plugin from Claude Code.
+
+Setup backups live under `~/.planr/backups/<project-hash>/<timestamp>/`. Machine
+state and paths live under `~/.planr/runtime/state.json`; the committed project
+lock contains only versions and compatibility capabilities.
+
+If an older installer created `~/CLAUDE.md`, `~/AGENTS.md`, Cursor rules, or a
+home-directory runtime lock, `planr doctor` reports `home-project-install`.
+Run `planr doctor --fix` to preview removal. Only recorded OpenPlanr-owned bytes
+are removed; user-scope adapters and hand-written content are retained.
+
+---
+
+## "No .planr/config.json found"
+
+You need to initialize Planr in your project first:
+
+```bash
+planr init
+```
+
+If you're running from a subdirectory, use `--project-dir`:
+
+```bash
+planr status --project-dir /path/to/project
+```
+
+---
+
+## Artifact review issues
+
+### `E_PIPELINE_NOT_INSTALLED`
+
+Artifact review is part of the full distribution. A planning-only install made
+with `--minimal` omits it. Install the full package and verify again:
+
+```bash
+npm install -g openplanr@latest
+planr doctor
+```
+
+### `E_ARTIFACT_STALE_REVIEW`
+
+The returned review targets a different artifact digest. Do not merge it
+silently. If the older feedback is still useful, rerun the import with
+`--allow-stale`, inspect the preview, and confirm. CI must also pass `--yes`.
+
+### A remote or SSH browser cannot reach the local review
+
+`planr artifact` intentionally binds to `127.0.0.1`. Use `--no-open --json`,
+then forward the printed port over SSH. Do not bind the review server publicly.
+
+### An artifact dependency is rejected
+
+The bundler resolves local dependencies below `--root` (the artifact's directory
+by default) and vendors supported public HTTPS dependencies automatically. It
+still rejects forms, path traversal, symlink escapes, private or non-HTTPS
+hosts, unsupported resources, and unresolved dependencies. Use `--root` when
+the artifact intentionally depends on a larger local asset tree.
+
+See [Artifact review and private sharing](ARTIFACT_REVIEW.md) for the complete
+privacy and sharing model.
+
+---
+
+## Cross-reference issues
+
+### Links point to wrong files
+
+If artifacts were renamed or moved manually, cross-references may break. Run:
+
+```bash
+planr sync --dry-run    # preview what would change
+planr sync              # fix broken links
+```
+
+### "Stale link" warnings
+
+A parent artifact links to a child that no longer exists on disk. `planr sync` removes these automatically.
+
+### "Missing link" warnings
+
+A child artifact references a parent, but the parent doesn't list the child. `planr sync` adds the missing link.
+
+---
+
+## Template issues
+
+### Custom templates not loading
+
+Make sure `templateOverrides` in `.planr/config.json` points to the correct directory:
+
+```json
+{
+  "templateOverrides": "./my-templates"
+}
+```
+
+The override directory must mirror the default template structure (e.g., `my-templates/epics/epic.md.hbs`). Only files that exist in the override directory will be used — all others fall back to defaults.
+
+---
+
+## GitHub integration issues
+
+### "GitHub CLI (gh) is not installed"
+
+The `planr github` commands require the GitHub CLI. Install it:
+
+```bash
+# macOS
+brew install gh
+
+# Other platforms: https://cli.github.com/
+```
+
+### "Not authenticated with GitHub"
+
+You need to log in with `gh`:
+
+```bash
+gh auth login
+```
+
+### "No GitHub remote found"
+
+Your repository doesn't have a GitHub remote configured. Add one:
+
+```bash
+git remote add origin https://github.com/your-org/your-repo.git
+```
+
+### "Could not resolve to an issue"
+
+The linked GitHub issue was deleted. Planr handles this gracefully — it will create a new issue on the next push. If you see this error during sync, re-push the artifact:
+
+```bash
+planr github push EPIC-001
+```
+
+### Push creates duplicate issues
+
+Each artifact stores its linked issue number in frontmatter (`githubIssue: 123`). If you manually delete this field, a new issue will be created on the next push. Don't edit `githubIssue` fields manually.
+
+---
+
+## Build and development issues
+
+### "Cannot find module" errors after changes
+
+Rebuild the project:
+
+```bash
+npm run build
+```
+
+Templates are copied during build. If you modified templates in `src/templates/`, they won't take effect until you rebuild.
+
+### Tests failing locally
+
+Make sure you have the correct Node.js version:
+
+```bash
+node --version    # should be >= 20.0.0
+```
+
+Install dependencies and run tests:
+
+```bash
+npm ci
+npm test
+```
+
+---
+
+## Still stuck?
+
+Open an issue at [github.com/openplanr/OpenPlanr/issues](https://github.com/openplanr/OpenPlanr/issues) with:
+
+- The command you ran
+- The full error output
+- Your Node.js version (`node --version`)
+- Your OS

package/lib/dashboard-verifier.d.mts

@@ -0,0 +1,29 @@
+export const DASHBOARD_BUNDLE_BUDGETS: Readonly<{
+  maxJavaScriptBytes: number;
+  maxCssBytes: number;
+  maxRuntimeAssetBytes: number;
+  maxSourceMapBytes: number;
+}>;
+
+export const DASHBOARD_ASSET_ERROR_CODES: Readonly<{
+  MISSING: 'E_DASHBOARD_ASSETS_MISSING';
+  MANIFEST_INVALID: 'E_DASHBOARD_MANIFEST_INVALID';
+  ASSETS_INVALID: 'E_DASHBOARD_ASSETS_INVALID';
+}>;
+
+export function verifyDashboardAssets(root?: string): Readonly<{
+  ok: boolean;
+  code: string | null;
+  problem: string | null;
+  root: string;
+  violations: readonly string[];
+  buildId: string | null;
+  assetManifestHash?: string | null;
+  assets: readonly Readonly<{
+    path: string;
+    bytes: number;
+    sha256: string;
+    kind: string;
+  }>[];
+  sizes: Readonly<Record<string, number>>;
+}>;