diff --git a/README.md b/README.md index d7acc68..e4dd95b 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ tmux attach -t my-agent | `pluk watch ` | Classify stdin line-by-line | | `pluk send --text="..." --enter` | Send text to a tmux session | | `pluk patterns --cli=claude` | Show loaded patterns for a CLI | +| `pluk version` | Print the installed version | | `pluk --help` / `-h` | Show usage (works after any subcommand) | Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name for "pluk " (see pluk --help)`) instead of being silently ignored. For example, `pluk sessions --cli=claude` is rejected: `--cli` belongs to `attach`, `watch`, and `patterns`, not `sessions`. Run `pluk --help` for the per-command flag lists. @@ -116,7 +117,7 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name | `--cli=claude` | CLI type: `claude`, `copilot`, `gemini`, `goose`, `codex`, `aider`, `omp` | | `--command=` | Override the CLI command/executable to launch (instead of the default resolved from `--cli`); combines with `--cli-args` | | `--rationguard` | Start rationguard watcher alongside pluk (requires `rationguard` on `PATH` — `npm install -g @hivecommons/rationguard` — or `--rationguard-bin`; pluk never fetches it from the registry implicitly) | -| `--rationguard-bin=` | Explicit rationguard command to run instead of the one on `PATH`, e.g. `--rationguard-bin='npx --yes @hivecommons/rationguard@0.11.0'` (also `PLUK_RATIONGUARD_BIN`); the flag is ignored with a warning without `--rationguard` | +| `--rationguard-bin=` | Explicit rationguard command to run instead of the one on `PATH`, e.g. `--rationguard-bin='npx --yes @hivecommons/rationguard@0.13.0'` (also `PLUK_RATIONGUARD_BIN`); the flag is ignored with a warning without `--rationguard` | | `--rebuttal=log\|send` | Log rebuttals or auto-send them when rationguard detects excuses; other values exit with code 2 before attaching. Ignored with a warning without `--rationguard` | | `--dangerous` | Skip CLI permission prompts (`--dangerously-skip-permissions` for claude, `--allow-all-tools` for copilot, `--full-auto` for codex, `--non-interactive` for goose, `--approval-mode yolo` for omp) | | `--dir=/path` | Working directory for the agent | @@ -138,7 +139,7 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name | `patterns` | `--patterns-dir=` | Show the patterns loaded from this directory (same lookup as `watch`) | | `subscribe` | `--from-beginning` | Replay the existing log from the start instead of only new lines | | `subscribe` | `--verbose` | Show debug output | -| `sessions`, `subscribe` | `--run-dir=` | Run directory to read (overrides `PLUK_RUN_DIR`) | +| `sessions`, `subscribe`, `watch` | `--run-dir=` | Run directory to use (overrides `PLUK_RUN_DIR`); `attach` accepts it too | | `sessions` | `--json` | Print the session list as JSON instead of a table | ### Health diagnostics (`watch`, `subscribe`) diff --git a/ROADMAP.md b/ROADMAP.md index 8d3eed1..ae2fad6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -11,22 +11,25 @@ package and its relationship with the wider Hive Commons agent-tooling stack. - Built-in pattern sets for Claude, Copilot, Gemini, Goose, Codex, Aider, and Oh My Pi (`omp`). - Rationguard integration through `pluk attach --rationguard` and stable event fields consumed by companion tools. +- A versioned JSONL event envelope (`v: 1`) with documented compatibility + rules in the README's [Event Schema](README.md#event-schema) section. ## Near term -1. **Event schema stability:** document compatibility expectations for the JSONL - event format so tools such as rationguard and hotshot can depend on it safely. +1. **Event schema evolution:** keep the JSONL envelope additive within schema + version 1 and define the process for a version bump, so tools such as + rationguard can depend on it safely. 2. **Broader CLI coverage:** add and test pattern packs for additional active agent CLIs as they become adoption-relevant. 3. **Operational hardening:** continue replacing tmux/terminal edge cases with explicit diagnostics, non-zero exits for operator errors, and hermetic tests. -## Go and TypeScript relationship +## Implementation -The TypeScript package is the npm-facing implementation for JavaScript users and -companion tools. The Go implementation remains useful where a static binary is -preferred. Near-term work should keep event shapes and user-facing semantics -aligned rather than forcing a repository merge. +Pluk is a single TypeScript package published to npm as `@hivecommons/pluk`; +there is no separate Go binary. Hive and other consumers shell out to the npm +CLI and read its JSONL logs, so event shapes and user-facing semantics are the +compatibility surface. ## Non-goals for now diff --git a/runbooks/publish-failure.md b/runbooks/publish-failure.md index 8b43fce..d7b02a6 100644 --- a/runbooks/publish-failure.md +++ b/runbooks/publish-failure.md @@ -1,7 +1,8 @@ # Runbook: a tag push whose publish pipeline failed -`publish.yml` runs three jobs on every `v*` tag push: `verify-tag`, then -`publish` (npm), then `release` (GitHub release). Which job failed decides the +`publish.yml` runs three jobs on every `v*` tag push (and when +`auto-release.yml` dispatches it after a version-bump merge): `verify-tag`, +then `publish` (npm), then `release` (GitHub release). Which job failed decides the recovery. For a version that already reached npm and is bad, use `release-rollback.md` instead. diff --git a/runbooks/release-rollback.md b/runbooks/release-rollback.md index 9788aab..c95f5cf 100644 --- a/runbooks/release-rollback.md +++ b/runbooks/release-rollback.md @@ -1,7 +1,9 @@ # Runbook: rolling back a bad pluk release -`publish.yml` runs `npm test` against the tagged ref and then publishes to npm -on every `v*` tag push. Tests reduce risk but cannot catch every regression +Merging a `package.json` version bump to `main` makes `auto-release.yml` +create the `v` tag and dispatch `publish.yml` (a manual `v*` tag +push also triggers it). `publish.yml` runs `npm test` against the tagged ref +and then publishes to npm. Tests reduce risk but cannot catch every regression (for example, behavior that only breaks under a real tmux session, a downstream consumer's assumptions, or an environment-specific failure). This runbook covers what to do once a bad version has already reached the npm @@ -54,12 +56,14 @@ packaging nit. 1. Branch from `main`, fix the regression, and add a regression test per `CONTRIBUTING.md`. -2. Bump the version in `package.json` and land the fix through the normal PR - process. -3. Tag `vX.Y.Z` on `main` once merged; `publish.yml` runs the test suite - against that tag and publishes automatically. -4. Add a `changelog.d/fixed-.md` fragment describing the regression and +2. Add a `changelog.d/fixed-.md` fragment describing the regression and the fix, following the existing entries in `changelog.d/`. +3. Bump the version in `package.json`, roll the fragments into a non-empty + `## X.Y.Z` section of `CHANGELOG.md`, and land the fix through the normal + PR process. +4. On merge, `auto-release.yml` tags `vX.Y.Z` and dispatches `publish.yml`, + which runs the test suite against that tag and publishes automatically. + If tagging or dispatch fails, see `publish-failure.md`. ## After diff --git a/runbooks/session-monitoring-failure.md b/runbooks/session-monitoring-failure.md index b56b90c..f268ecc 100644 --- a/runbooks/session-monitoring-failure.md +++ b/runbooks/session-monitoring-failure.md @@ -46,8 +46,9 @@ A silent watcher means those consumers act on stale state. | `eventsFiltered` ≈ `linesSeen` | `--filter` excludes everything | Review the filter set | | `malformedLines` rising (subscriber) | Log has non-pluk lines | Check for another writer on the log file or truncated rotation | -If counters are healthy and events still do not arrive, the CLI may have no -bundled patterns (`codex`, `aider`): pass `--patterns-dir`. +If counters are healthy and events still do not arrive, check that a pattern +set exists for the CLI name you passed (`pluk patterns --cli=` lists the +bundled sets); for an unsupported CLI, pass `--patterns-dir`. ## Recover