Merge yaqub0r/devclaw-local-stable — dev tree docs & runbooks

dev/README.md

@@ -0,0 +1,40 @@
+# DevClaw developer tree
+
+This `dev/` tree is the canonical in-repo home for developer-only material.
+It is versioned with the repository so developer guidance and regression artifacts travel with the codebase, but it is not intended to be part of the end-user release payload.
+The tree should remain in git, while `package.json.files` should continue to exclude `dev/` so these artifacts are not shipped by default.
+
+## Required layout
+
+The intended top-level artifact layout under `/dev` is:
+
+- `dev/README.md`, the top-level guide to the developer-only tree
+- `dev/runbooks/`, for developer and operator runbooks, including self-hosting guidance
+- `dev/regression/tests/`, for executable regression coverage
+- `dev/regression/issues/`, for issue-linked notes, bug summaries, and validation rationale
+- `dev/regression/fixtures/`, or equivalent supporting fixture/helper material when tests need stable inputs
+
+At minimum, the developer tree should contain:
+
+- `dev/README.md`, the top-level guide to the developer-only tree
+- `dev/runbooks/`, for developer and operator runbooks
+- self-hosting documentation under `dev/runbooks/`
+- `dev/regression/tests/`, for executable regression coverage
+- `dev/regression/issues/`, for issue-linked notes, bug summaries, and validation rationale
+- `dev/regression/fixtures/`, or equivalent supporting fixture/helper material when tests need stable inputs
+
+Release-user documentation stays under `docs/`.
+Developer-only runbooks, issue-linked regression notes, and release-hardening checks belong under `dev/`.
+
+## Definition of Done for release-relevant fixes
+
+Do not consider an issue done until the regression story is addressed.
+Issues are not considered done until regression tests are added when appropriate, along with any supporting rationale or fixtures under `/dev`.
+
+When a bug fix is release-relevant or likely to regress, the issue is not done until the regression story is addressed:
+
+1. add or update executable regression coverage under `dev/regression/tests/`
+2. document the bug summary, triggering conditions, automated coverage, and any manual validation notes under `dev/regression/issues/`
+3. add fixtures or helpers under `dev/regression/fixtures/` when the regression needs stable inputs
+
+If a fix does not need a regression artifact, the developer handling the issue should be able to explain why.

dev/regression/issues/dev-tree-cleanup-105.md

@@ -0,0 +1,30 @@
+# Regression note: repo-local developer tree cleanup, issue #105
+
+- Related issue: #105
+- Scope: preserve repo-local developer guidance under `dev/` while keeping `dev/` out of the published package payload
+
+## Change summary
+
+This cleanup keeps the self-hosting runbook under `dev/runbooks/`, makes the `/dev` layout and Definition of Done expectations explicit in `dev/README.md`, and preserves the packaging boundary that keeps `dev/` versioned in git but excluded from `package.json.files`.
+
+## Triggering conditions
+
+- documentation or cleanup work moves developer-facing material out of release-user docs
+- a packaging change risks shipping the repo-local `dev/` tree in the published package
+- follow-up cleanup needs to confirm where regression artifacts and issue-linked notes belong
+
+## Automated coverage
+
+The existing repo checks for this cleanup are:
+
+1. `npm run check`, to confirm the repo still type-checks after the documentation and packaging-boundary cleanup
+2. `npm run regression:release`, to confirm the release regression suite still passes with the current `dev/` tree layout
+
+## Manual validation notes
+
+This issue is documentation and packaging-boundary cleanup, so no new executable regression script was added.
+Manual validation should confirm that:
+
+- `dev/runbooks/developing-devclaw-with-openclaw.md` still contains the preserved self-hosting sections
+- `dev/README.md` explains the intended `/dev` layout and DoD expectations
+- `package.json.files` does not include `dev/`

dev/runbooks/developing-devclaw-with-openclaw.md

@@ -0,0 +1,209 @@
+# Developing DevClaw with OpenClaw
+
+This guide covers the generic workflow for developing DevClaw while running DevClaw through OpenClaw.
+
+It is intentionally environment-agnostic. If your machine or fork has local policy, branch names, or operator habits layered on top, keep those in local-only docs and link back here.
+This runbook lives under `dev/runbooks/` because it is self-hosting and developer-facing guidance, not release-user documentation.
+
+## What this guide is for
+
+Use this when you are:
+
+- editing DevClaw source while DevClaw is your active orchestrator
+- switching the live plugin source between branches or worktrees
+- validating that a branch change actually became the runtime source
+- avoiding duplicate plugin-source loads during local development
+
+## Core idea
+
+A branch does not become live because you checked it out.
+
+A branch becomes live when OpenClaw is loading the DevClaw plugin from that checkout or worktree.
+
+That means branch switching for DevClaw development is really a **plugin source switch** followed by a **runtime verification** step.
+
+## Recommended branch roles
+
+These are roles, not mandatory branch names:
+
+- **clean integration branch**: the branch that tracks the normal upstream line
+- **working branch**: a feature or fix branch carrying in-progress changes
+- **fallback branch**: an optional known-good branch you can switch back to quickly
+- **local docs branch**: an optional branch for operator runbooks that are not meant for upstream
+
+Use names that fit your repo. The workflow matters more than the naming.
+
+## Safe live-switch procedure
+
+When changing the live DevClaw source during development:
+
+1. Choose the target checkout or worktree.
+2. Build that target source tree.
+3. Confirm the built artifact exists.
+4. Make sure only one DevClaw plugin source is active.
+5. Point OpenClaw at the intended source path.
+6. Restart the gateway.
+7. Verify the loaded plugin path.
+8. Verify the exact live git commit.
+
+## Build before switching
+
+Before switching live, verify the target source tree has a built artifact:
+
+```bash
+test -f <target-source-root>/dist/index.js && echo built || echo missing-dist
+```
+
+If `dist/index.js` is missing, build first and do not switch the live source yet.
+
+## Verify the live source path
+
+The source of truth is the live plugin inspection output, not memory and not the checkout you happen to be editing.
+
+```bash
+openclaw plugins inspect devclaw
+openclaw gateway status
+```
+
+Use `openclaw plugins inspect devclaw` to answer:
+
+- what path is actually live
+- which plugin version is loaded
+
+Important distinction:
+
+- `inspect` tells you **what path is live**
+- git tells you **what commit that path contains**
+
+## Verify the exact live commit
+
+Once you know the live source path, resolve that path back to the checkout or worktree root and verify the commit directly:
+
+```bash
+openclaw plugins inspect devclaw
+git -C <live-source-root> rev-parse HEAD
+```
+
+Do not assume that the installed extension directory or your current shell checkout is the live commit.
+
+## Stronger proof for linked local installs
+
+If you are using a linked local install and want stronger proof that the live plugin really comes from the intended worktree, verify both the install path target and the branch name:
+
+```bash
+openclaw plugins inspect devclaw
+readlink -f ~/.openclaw/extensions/devclaw
+git -C <intended-worktree> rev-parse --abbrev-ref HEAD
+git -C <intended-worktree> rev-parse HEAD
+```
+
+This gives you four checks:
+
+- the live plugin id and loaded source
+- the real filesystem target behind the installed extension path
+- the branch name of the intended worktree
+- the exact commit of that worktree
+
+For example, if you intend to run from a `feature/self-hosting-fix` worktree, these checks should agree on both the path and the branch identity before you treat the switch as complete.
+
+## Avoid duplicate plugin-source collisions
+
+A common failure mode is loading DevClaw from more than one place at once, for example:
+
+- an installed copy under `~/.openclaw/extensions/devclaw`
+- and a path/worktree load via `plugins.load.paths[]`
+
+If both are in play, the gateway may load a different source than the one you intended.
+
+If startup logs mention duplicate plugin ids or the runtime path does not match your expected worktree, stop and clean up the duplicate before trusting the switch.
+
+## When a live switch failed
+
+Treat the switch as failed if any of the following happen:
+
+- `openclaw plugins inspect devclaw` reports the wrong source path
+- the plugin is missing after restart
+- startup logs show duplicate plugin warnings
+- the target source tree has no `dist/index.js`
+- the gateway is still loading an older installed copy
+
+In that case:
+
+1. verify the target build artifact exists
+2. inspect the live plugin path again
+3. remove or disable competing DevClaw plugin sources
+4. restart and verify again
+
+## Generic smoke test for a running environment
+
+Use this when you want to verify a local DevClaw install in an already-running environment without creating new projects or tasks.
+
+## Tracker routing verification for fork-based installs
+
+If your local checkout has both a fork and an upstream remote, do not trust ambient GitHub CLI repo inference.
+
+Before relying on issue-creation flows, verify both the configured tracker target and the checkout's ambient `gh` target:
+
+```bash
+python3 - <<'PY'
+import json
+p=json.load(open('devclaw/projects.json'))['projects']['devclaw']
+print(p['repoRemote'])
+PY
+git -C <repo-or-worktree> remote -v
+gh repo view --json nameWithOwner --jq .nameWithOwner
+```
+
+Expected safety rule:
+
+- DevClaw issue/task tooling must route to the repository configured in `projects.json`
+- it must not drift to the repo that `gh` happens to infer from the checkout context
+
+When validating a fix for tracker-routing bugs, record both:
+
+- a pre-change proof showing config target versus ambient `gh` target
+- a post-change proof showing issue/task creation calls explicitly target the configured repo
+
+Read-only checks:
+
+```bash
+openclaw plugins inspect devclaw
+openclaw plugins list
+openclaw gateway status
+openclaw agent --agent <agent-id> --message 'Call project_status with channelId "<channel-id>" and reply with the result only.' --json
+openclaw agent --agent <agent-id> --message 'Call tasks_status and reply with the result only.' --json
+openclaw agent --agent <agent-id> --message 'Call channel_list and reply with the result only.' --json
+```
+
+What this verifies:
+
+- the plugin is loaded
+- the gateway is healthy
+- the live agent can read local project state
+- the live agent can read tracker-backed task state
+- channel bindings are visible
+
+Expected result note:
+
+- in an unbound DM or admin session, `project_status` and `tasks_status` may correctly return `No project found` for that channel
+- treat that as a passing result for this smoke test unless you were specifically testing a known project-bound chat
+
+Avoid using project-creating or task-creating commands for smoke tests in a shared live environment unless you also have an explicit cleanup plan.
+
+## Keep generic guidance separate from local policy
+
+Generic repo docs should cover:
+
+- the branch/worktree switching model
+- build and verification steps
+- duplicate-source failure modes
+- how to reason about live source versus checked-out source
+
+Local-only docs should cover:
+
+- branch names used on one machine or fork
+- preferred fallback lanes
+- machine-specific paths
+- personal or operator-specific workflow habits
+
+That separation keeps the main docs useful in any environment while still allowing strong local runbooks.