wei-wuwei 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@ One section per published version, newest first. `wuwei update` prints the
 sections between the installed version and the new one before it asks;
 `wuwei check` fails when package.json's version has no section here.
 
+## 0.6.0
+
+- feat(brief): wuwei brief — the personal dashboard (stream personal-dashboard) (#75)
+
 ## 0.5.0
 
 - feat(plan-check): a script is an e2e harness too (#69)

package/README.md

@@ -56,7 +56,7 @@ wuwei update                             # newer version out? shows what it woul
 # from a clone:
 git clone git@github.com:jameshsiao/wuwei.git
 cd wuwei
-npm run check                        # lint frontmatter
+npm run check                        # validate frontmatter, lint references and budgets
 npm run build                        # emit repo-local artifacts (.claude/, .agents/, AGENTS.md, CLAUDE.md)
 node bin/wuwei.js init <project>     # repo scope: templates + .wuwei/ skeleton, then
                                      #   offers the tools below (and, with Codex, an execute
@@ -67,6 +67,9 @@ node bin/wuwei.js status <project>   # read-only: streams/claims from .wuwei, dr
 node bin/wuwei.js update             # git pull if behind, diff against what install wrote, apply on yes
 node bin/wuwei.js review-prep <base>  # wuwei-review's prep: dispatcher checks + scan bundle (or --pr <n>)
 node bin/wuwei.js claim [stream] [NN] # list eligible phases, or claim one: cut, claim, push
+node bin/wuwei.js brief <path>… [--json | --html | --md] [--write] [--open] [--mark] [--if-due 08:45] [--since 7d] [--stale 72h]  # your daily dashboard across repos: done, today,
+                                     #   left, what waits on you, and the PRs — a page on a terminal; see docs/brief/README.md
+node bin/wuwei.js brief <path>… --schedule [launchd|cron|claude-desktop] [--at 08:45]  # print the daily routine to paste; installs nothing
 node bin/wuwei.js review-collect     # each lens's transcript + report into the bundle, and what each one spent
 node bin/wuwei.js digest-check <f>   # a review digest's arithmetic before it is published
 node bin/wuwei.js plan-check [stream] # plan-phases step 11's checkable half, before sign-off
@@ -75,9 +78,12 @@ node bin/wuwei.js mutate <f>:<n> --from … --to … --run … --in <wt>  # one
 node bin/wuwei.js sites <pattern>… [--symbol <name>]  # a set derived from the tree, graph and grep both; several names in one call
 node bin/wuwei.js claims-scan <doc>… # a document's paths, names, file:lines and commands checked against the tree in one call
 node bin/wuwei.js verify [page] [--phase NN]  # every data-bearing page × 500/403/404/empty/pending/failed refetch; --phase: ACCEPTANCE's ## Verify; mobile: Maestro + mock server
-node bin/wuwei.js uninstall          # removes exactly what install wrote, nothing else
+node bin/wuwei.js uninstall          # user scope: removes the stamped files install wrote, and wuwei's rules blocks
+node bin/wuwei.js uninstall <path>   # a project: removes the templates whose text names wuwei — a team file that says "wuwei" goes too
 ```
 
+Every command, what it does and an example, is in [Commands](#commands) below.
+
 `update` is `install` with its eyes open. It first asks the channel this copy
 came from whether a newer version exists — git for a clone, npm for the
 package — and offers to move to it; the newer copy then runs the diff. Every
@@ -87,7 +93,8 @@ in `~/.wuwei/manifest.json`), `stale` (orphaned, would be removed) or
 `conflict` (a file at that path wuwei did not generate). Before that it prints
 `CHANGELOG.md`'s sections since the installed version. Nothing is written
 without a yes; `edited` and `conflict` files are copied to
-`~/.wuwei/local-patches/<time>/` first; `--dry` only reports.
+`~/.wuwei/local-patches/<time>/` first; `--dry` only reports
+(it still asks git or npm first).
 
 You don't have to remember to run it: once a day any `wuwei` command checks
 npm in the background, and when a newer version is out it says so on stderr
@@ -105,12 +112,64 @@ tests-only merge releases nothing; *Run workflow* (`workflow_dispatch`) with a
 bump releases now. A version already set in `package.json` that npm has not
 seen goes out as is.
 
+## Commands
+
+Every command the CLI accepts, and what it does — each row written from the
+command's own code. `wuwei` is also `ww` and `wei-wuwei`; from a clone, run
+`node bin/wuwei.js` in its place. Bare `wuwei` is `wuwei build`.
+
+| Command | What it does | Example |
+|---|---|---|
+| [`init [path]`](#tools-it-will-offer-you) | Bootstraps a project (default: the current directory): the PR template, `.wuwei/templates/` and a `.wuwei/STATE.md` skeleton. Then, only where they help, it offers a `.planning/` (GSD) import, codegraph, semgrep and osv-scanner, and — if Codex has run — an execute profile in `$CODEX_HOME/config.toml`; it ends by naming the next step | `wuwei init` |
+| [`install [path]`](#quick-start) | With no path, once per machine: skills and agents into `~/.claude`, rules into `~/.claude/CLAUDE.md` and, if Codex has run, skills into `~/.agents/skills` and rules into `$CODEX_HOME/AGENTS.md`; what it wrote is recorded in `~/.wuwei/manifest.json`, and it offers `npm install -g`. With a path, only that project's templates and `.wuwei/STATE.md` | `npx wei-wuwei install` |
+| [`update`](#quick-start) | Asks the channel this copy came from (git for a clone, npm for the package) whether a newer one exists and offers to move to it; then shows what `install` would change — `new`, `changed`, `edited`, `stale`, `conflict` — and applies it on a yes, copying your edits to `~/.wuwei/local-patches/` first. Off a terminal, or with `--dry`, it changes no file of yours — it still asks git (`git fetch`) or npm first. `--no-fetch` skips that question | `wuwei update` |
+| [`uninstall [path]`](#tools-it-will-offer-you) | Without a path, takes back what `install` wrote: the skills and agents in `~/.claude` and the skills in `~/.agents/skills` that carry wuwei's `GENERATED BY wuwei` stamp, wuwei's block in `~/.claude/CLAUDE.md` and `$CODEX_HOME/AGENTS.md`, the Codex profile `init` added and `~/.wuwei/manifest.json`; then it offers to take back the global command, codegraph and the scanners (semgrep, osv-scanner), each only where it is still installed. With a path, the project's PR template and `.wuwei/templates/*.md` **whose text names wuwei** — those templates carry no stamp, so a team file at one of those paths that mentions wuwei is removed too; `.wuwei/STATE.md` and `streams/` are kept, and the one offer is codegraph's `uninit`, where `.codegraph/` is. It has no `--dry`: it removes | `wuwei uninstall` |
+| `build` | Emits this checkout's repo-local artifacts from `skills/` and `agents/`, for the targets `wuwei.config.json` enables: `.claude/`, `CLAUDE.md`, `AGENTS.md` and `.agents/skills/`. What `wuwei` runs with no command | `npm run build` |
+| `check` | Validates every skill's and agent's frontmatter, then lints them: a number that counts a list below it, a `wuwei-…` name or `§N` that no longer exists, word budgets, `modelRoles` against the agent files, and a `CHANGELOG.md` section for this version. Exit 1 with the list on a failure; CI runs it | `npm run check` |
+| `list` | Prints the skills (marked `[always]` for a rule, `[local]` for one that stays in the repo), the agents and the templates this copy holds | `wuwei list` |
+| `status [path]` | Read-only: the streams `.wuwei/STATE.md` lists against the directories under `.wuwei/streams/`, each mismatch it can prove flagged, and a warning when `.codegraph/` is tracked by git | `wuwei status ~/work/app` |
+| `claim [stream] [phase]` | A stream's phases and where each stands (`ready`, `claimed`, `merged`, `waiting`, `blocked`), whether its stream branch is current, and the model each step dispatches. With a phase it cuts that phase's branch from the stream branch, writes `claimed-by` and `claimed-at` into the phase file, commits and pushes. It refuses a merged, waiting or claimed phase (`--take-over` records a takeover), a stale stream branch and a dirty checkout. `--by <who>` names the claimer; without it, a claim made from inside a Claude Code session (its `CLAUDE_CODE_SESSION_ID`, when that is a uuid) writes `claimed-by: <user>@<host> (session <uuid>)`, which `brief` reads to find the session; `--dry` stops before the branch is cut, so it changes no file of yours — `claim` always runs `git fetch origin` first | `wuwei claim my-stream 03` |
+| [`brief <path>…`](docs/brief/README.md) | Across every wuwei repo under the paths: what got done since you last looked, what you can start today, what is left, what waits on you, and the PRs. On a terminal it writes the report as a web page to `~/.wuwei/brief/brief.html` and opens it; off one (a pipe, a file, an agent) it prints markdown. `--md` the markdown, `--json` the data, `--html` the page on stdout, `--write` the page whatever stdout holds, `--open` show the page it writes, `--mark` start the next window here, `--if-due 08:45` do nothing new when a routine has run since then (what every routine passes), `--since 7d` look further back, `--stale 48h` when a claim without commits is stale, `--lang zh-TW` the report's own words in 繁體中文 (or in a language you write: `--lang-template` prints the table to translate), `--schedule [launchd\|cron\|claude-desktop] [--at 08:45]` prints a daily routine to paste and installs nothing | `wuwei brief ~/work` |
+| `plan-check [stream]` | wuwei-plan-phases step 11's checkable half, before sign-off: the `## Sign-off` fields, a stream branch ending `/base` and on origin, `depends-on` that resolves without a cycle (phases and tasks), the task diagram matching those fields, `## Verify` bound to phases, a harness named, and `STATE.md` agreeing with `phases/`. Exit 1 on any error | `wuwei plan-check my-stream` |
+| `review-prep [base]` | wuwei-review's prep: fetches the base and writes the bundle `.wuwei-cache/review/<sha>/` — `INDEX.md`, `diff.patch` and `PREP.md` (merges cleanly, CI at HEAD, tool-maintained deletions, author paths) — plus semgrep's output and, for a changed lockfile, osv-scanner's, where they are installed. `--pr <n>` reads a PR and its thread, `--path <p>` reviews a path with no base, `--no-scan` skips the scanners | `wuwei review-prep main` |
+| `review-collect` | Copies each lens's transcript and report from the newest Claude Code session here that dispatched a wuwei lens into the bundle's `reports/`, and prints what each one spent. `--session <id>` picks another session; `--sha <sha>` another bundle, by the 12-character sha `review-prep` named it by — used as the directory name, not resolved, so `--sha 3252957f2bcd`, not `--sha main` | `wuwei review-collect` |
+| `verify [page]` | Walks each page of `.wuwei/verify.json` through a 500, 403, 404, empty, pending and a failed refetch — in Chromium (Playwright) against a mock of the API, or, for a mobile app, on a simulator with Maestro — and writes a matrix and screenshots under `.wuwei-cache/verify/<sha>/`. `--phase NN` runs the pages ACCEPTANCE.md binds to that phase, and with more than one stream under `.wuwei/streams/` it needs `--stream <name>` to say whose | `wuwei verify --phase 04 --stream my-stream` |
+| `digest-check <digest.md>` | A review digest's arithmetic before it is published: raw = rows + merged + dropped, the numbering, reporter credits, every `file:line` and identifier against the reviewed tree, no HIGH that is PLAUSIBLE, no secret, the verdict's two axes, and whether HEAD moved. Exit 1 on an error | `wuwei digest-check digest.md` |
+| `worktree <lens> [sha]` | A throwaway detached git worktree in the temp directory, named for the sha and the lens so no two lenses share one; prints its path and nothing else. `--prune [sha]` removes them | `cd "$(wuwei worktree defects HEAD)"` |
+| `mutate <file>:<line>` | One mutation, inside a worktree `wuwei worktree` made: replaces `--from` (which must occur once on that line) with `--to`, runs `--run` before and after, puts the file back, and says `caught` or `survived` when it can read the runner's failure count, `green by exit code` or `red by exit code` when it cannot, and `did not land` when the file did not change; the run is recorded under `.wuwei-cache/review/<sha>/mutations/`. `--in <worktree>` names the tree, `--no-baseline` skips the first run. Exit 2 if the file could not be restored | `wuwei mutate src/pay.js:42 --from '>=' --to '>' --run 'npm test' --in "$WT"` |
+| `sites <pattern>…` | A set derived from the tree: every site of each pattern by `git grep`, with the command printed beside the count. `--symbol <name>` also asks codegraph for its callers and says where graph and grep disagree; `--regex` reads each pattern as an extended regex (`-E`; the default is a fixed string, `-F`), `--sha <rev>` greps that revision instead of `HEAD`, `-- <pathspec>` only those paths | `wuwei sites parseFrontmatter signOffField` |
+| `claims-scan <doc>…` | A document's code-span paths, `file:line`s, commands and names checked against the tree in one pass; counts and commands it cannot check are listed for judgment. `--sha <rev>` reads the tree there, `--all` lists what held too | `wuwei claims-scan README.md` |
+| `--version`, `-v`, `version` | Prints this copy's version | `wuwei --version` |
+| `--dry` | A flag, not a command: on `build`, `init`, `install`, `update` and `claim` it says what would be written and changes no file of yours; `claim` and `update` still fetch (`git fetch`, or npm's registry for the package). `uninstall` does not take it | `wuwei install --dry` |
+
+## `wuwei brief` — your daily dashboard
+
+One command each morning, across every wuwei repo you work in: **what got done
+since you last looked, what you can start today, what is left, and what waits
+on you** — read from each stream at origin, with your pull requests added when
+the GitHub CLI is logged in. On a terminal the report is a web page, written to
+`~/.wuwei/brief/brief.html` and opened in your browser; off one it is markdown.
+
+```sh
+wuwei brief ~/work
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Jameshsiao/wuwei/main/docs/img/brief/desktop-light.png" alt="The wuwei brief page on a desktop: a headline of what needs you — 8 CI failing, 7 ready to merge, 3 reviews requested — then the Needs you list, grouped by what to do, beside the phases in motion and each stream's progress" height="420">
+</p>
+
+From the test fixture — fake repos and a fake `gh`. Every flag, the report as
+markdown and JSON, the GitHub half, a daily routine and your own language are in
+the full guide: [`docs/brief/README.md`](docs/brief/README.md).
+
 ## Daily use
 
-The CLI above only installs and inspects. The work itself is driven by the ten
-skills, invoked by name or triggered by what you say. A stream runs
-**grill → brainstorm → plan → execute**, with a human at exactly two points:
-sign-off before anything is built, and UAT at the end.
+The CLI above installs wuwei, reads and checks the plan, and does the mechanical
+halves of what the skills ask for — claiming a phase, a review's prep, one
+mutation's run. The work itself is driven by the ten skills, invoked by name or
+triggered by what you say. A stream runs **grill → brainstorm → plan →
+execute**, with a human at exactly two points: sign-off before anything is
+built, and UAT at the end.
 
 ```
 /wuwei-grill            # interrogate the requirement — no solutions yet
@@ -190,26 +249,6 @@ changed and cannot show what depends on it, which is why the first row gates
 severity: "no call site left behind" is a claim a graph settles and reading
 harder never will.
 
-## Repo layout
-
-```
-wuwei/
-├── skills/            # canonical skill definitions (source of truth)
-│   └── _template/
-├── agents/            # canonical subagent definitions
-│   └── _template/
-├── templates/         # PR / review templates, installed per-repo
-├── bin/wuwei.js       # CLI: build · check · list · init · install · update · status · review-prep · review-collect · claim · digest-check · plan-check · worktree · mutate · sites · claims-scan · verify · uninstall
-│                      #   the per-tool emitters live here too, not in adapters/
-├── adapters/          # notes only — see bin/wuwei.js for the actual emitters
-├── docs/
-│   ├── product.md     # what wuwei is now (edited in place)
-│   ├── decisions.md   # why it got here (append-only)
-│   ├── architecture.md
-│   └── authoring.md
-└── wuwei.config.json  # sources + targets; `commands` is declared but not built yet
-```
-
 ## Design principles
 
 1. **One source of truth.** A skill is defined once. Everything else is generated.