@unbrained/pm-cli 2026.6.16 → 2026.6.17

package/docs/COMMANDS.md

@@ -25,12 +25,13 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 | Bootstrap | `init`, `config`, `health`, `telemetry` | create and inspect tracker setup |
 | Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit`* | find work and audit decomposition |
 | Lifecycle | `create`, `copy`, `focus`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
+| Scheduling | `meet`, `event`, `remind` | low-friction Meeting/Event/Reminder creation |
 | Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
 | Logs | `comments`, `notes`, `learnings`, `comments-audit` | record progress and durable context |
 | Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
 | History | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats` | inspect, compact, redact, re-anchor, and recover item state |
-| Schema | `schema add-type` / `remove-type` / `add-status` / `remove-status` | manage config-driven custom item types (`.agents/pm/schema/types.json`) and statuses (`.agents/pm/schema/statuses.json`) |
+| Schema | `schema add-type` / `remove-type` / `add-status` / `remove-status` / `add-field` / `remove-field` / `apply-preset` | manage config-driven custom item types (`.agents/pm/schema/types.json`), statuses (`.agents/pm/schema/statuses.json`), and custom metadata fields (`.agents/pm/schema/fields.json`); `apply-preset` adopts a domain type preset; `add-type --infer` derives types from title-prefix conventions |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
 | Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
 | Machines | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
@@ -347,6 +348,24 @@ pm pause-task <id>             # move to open + release claim
 pm close-task <id> "<reason>"  # close + release assignment
 ```
 
+After `pm create` of a workable item type, the result includes a non-binding `next_transition` hint (`pm start-task <id>` → `in_progress`) when the workflow defines a distinct in-progress status. This nudges agents to move work through `in_progress` instead of jumping straight from `open` to `closed`. Scheduling/reference types (Event, Meeting, Reminder, Milestone, Decision) never receive the hint. (GH-216)
+
+## Scheduling Shortcuts
+
+Low-friction creation for the scheduling item types so time-based tracking feels native. Each command translates friendly time flags into the canonical `--event`/`--reminder` fields and delegates to `pm create` (parent/focus inheritance, governance, and validation all still apply). The `lightweight` schedule preset is applied so progressive scheduling fields are not demanded up front. (GH-217)
+
+```bash
+pm meet "Sprint Planning" --start +1h --duration 1h          # Meeting (start defaults to now, duration to 1h)
+pm event "Release v2" --start 2026-07-01T10:00:00Z --duration 2h --location "Room A"
+pm remind "Review PR" --at +2d                               # Reminder (--at defaults to +1d, text defaults to the title)
+```
+
+- `--start`/`--at`/`--end` accept ISO timestamps, `now`, or relative tokens (`+1h`, `+2d`, `+2w`, `+6m`).
+- `pm meet`/`pm event` take `--start`, `--duration` (or `--end`), `--location`, `--timezone`, and `--all-day`; passing `--end` overrides `--duration`.
+- `--duration` uses the same relative units as `--event duration=`: `h` (hours), `d` (days), `w` (weeks), `m` (**months**, not minutes). For sub-hour spans set an explicit `--end`.
+- `pm remind` takes `--at` and `--text` (text defaults to the title).
+- Common create flags also apply: `--parent`, `--allow-missing-parent`, `--tags`, `--priority`, `--body`, `--description`, `--author`, `--message`.
+
 ## Ownership
 
 ```bash
@@ -384,6 +403,8 @@ pm deps <id> --format tree
 
 Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships. The standalone `--note <text>` flag annotates every link added by `--add`/`--add-glob` in the same invocation (a per-entry embedded `note=` wins); `--note` without an add is a usage error.
 
+Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; `--dep` accepts `id,kind,type,author,created_at` (plus `source_kind` on update); `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Bare values (`--add src/cli/main.ts`) skip key validation.
+
 ## Linked Tests
 
 ```bash
@@ -577,10 +598,17 @@ pm schema add-type Spike --alias spike --alias research --folder spikes
 pm schema remove-type Spike
 pm schema add-status review --role active --alias in_review --description "Awaiting review" --order 25
 pm schema remove-status review
+pm schema add-field severity_level --type string --commands create,update --description "Bug severity" --required-on-create
+pm schema list-fields
+pm schema show-field severity_level
+pm schema remove-field severity_level
+pm schema apply-preset agile
+pm schema add-type --infer --min-count 10
+pm schema add-type --infer --apply
 pm create Spike "Investigate retry backoff"
 ```
 
-- `pm schema list --json` returns `{ builtin, custom, extension, counts, statuses: { builtin, custom, counts } }` for compact machine parsing. Each status entry includes `id`, `source` (`builtin`/`custom`), `roles`, and `aliases`.
+- `pm schema list --json` returns `{ builtin, custom, extension, counts, statuses: { builtin, custom, counts }, fields: { custom, counts } }` for compact machine parsing. Each status entry includes `id`, `source` (`builtin`/`custom`), `roles`, and `aliases`; each field entry includes `key`, `type`, `commands`, `cli_flag`, `cli_aliases`, and the required/allow_unset flags.
 - `pm schema show <Type> --json` returns the resolved definition, including folder, aliases, default status, required create options, type options, command-option policies, and extension provenance when applicable.
 - `pm schema show-status <id> --json` returns one resolved status definition (builtin or custom) including `id`, `source`, `roles`, `aliases`, optional `description`, and optional `order`. Status aliases resolve automatically.
 - `add-type` is an idempotent UPSERT keyed on the type name (case-insensitive); re-running it merges aliases and overrides supplied fields while preserving everything else.
@@ -588,6 +616,10 @@ pm create Spike "Investigate retry backoff"
 - `add-status <id>` writes a custom lifecycle status (idempotent UPSERT keyed on the normalized id; re-adding sets `replaced: true`). Roles are validated against the runtime status roles: `draft`, `active`, `blocked`, `terminal`, `terminal_done`, `terminal_canceled`, `default_open`, `default_close`, `default_cancel`.
 - `remove-status <id>` removes a custom status. The five built-in default statuses (`open`, `in_progress`, `blocked`, `closed`, `canceled`, plus `draft`) are refused. It WARNS (non-blocking) with `items_using_status:<N>` when items currently use that status.
 - Built-in types (Chore, Decision, Epic, Event, Feature, Issue, Meeting, Milestone, Plan, Reminder, Task) are reserved and cannot be redefined or removed.
+- `add-field <key>` registers a custom metadata field in `.agents/pm/schema/fields.json` (shape: `{ "fields": [RuntimeFieldDefinition...] }`). Each custom field dynamically registers a CLI flag on create/update (and any other commands you list) so projects can capture typed project-specific metadata without hand-editing JSON. It is an idempotent UPSERT keyed on the normalized key, and refuses keys that shadow a built-in field. `list-fields` / `show-field <key>` inspect registered fields; `remove-field <key>` drops one and WARNS (non-blocking) with `items_using_field:<N>` when items still carry a value. See [CONFIGURATION.md](CONFIGURATION.md) for the full `schema/fields.json` format.
+- `apply-preset <agile|ops|research>` batch-registers a domain type preset into an already-initialized project (the same vocabulary `pm init --type-preset` seeds); it is idempotent (re-running reports `replaced` entries) and shares its definitions with init.
+- `add-type --infer` scans existing item titles for stable `PREFIX-`/`PREFIX:` conventions and proposes them as custom types. It previews candidates by default (dry-run); pass `--apply` to register the non-shadowing candidates and `--min-count <n>` to tune the per-prefix threshold (default 10). Candidates whose name resolves to a built-in type are reported and skipped.
+- Field flags (`add-field`): `--type <string|number|boolean|string_array>`, `--commands <list>` (repeatable/comma; defaults to create,update), `--cli-flag <flag>`, `--alias <flag>` (extra CLI flag aliases), `--required`, `--required-on-create`, `--no-allow-unset`, `--required-types <list>`.
 - Flags: `--description <text>`, `--default-status <status>`, `--folder <dir>`, `--alias <name>` (repeatable), `--role <value>` (repeatable; add-status), `--order <n>` (add-status), plus `--author`/`--force` governance flags. Add `--json` for the machine envelope.
 - When `pm create`/`pm update` reject an unknown type, the error now points back here: `To register a custom type, run: pm schema add-type "X" (writes .agents/pm/schema/types.json).`
 
@@ -597,7 +629,7 @@ pm create Spike "Investigate retry backoff"
 - `ops`: Incident, Runbook
 - `research`: Experiment, Hypothesis
 
-The option composes with `--defaults`, `--preset`, `--author`, `--agent-guidance`, and `--with-packages`; re-running it is idempotent and reports `registered_type_preset` in JSON output.
+The option composes with `--defaults`, `--preset`, `--author`, `--agent-guidance`, and `--with-packages`; re-running it is idempotent and reports `registered_type_preset` in JSON output. Already-initialized projects can adopt the same presets without re-running init via `pm schema apply-preset agile|ops|research`.
 
 ## Plan Workflow
 

package/docs/CONFIGURATION.md

@@ -73,6 +73,16 @@ When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and
 
 Runtime item types are context primitives. Use `pm schema list` to inspect the merged registry and `pm schema show <Type>` to inspect one type's folder, aliases, defaults, required options, and extension provenance. `pm init --type-preset agile|ops|research` writes reusable domain types into `.agents/pm/schema/types.json`; this is equivalent to persisted project schema, not an extension-only runtime overlay.
 
+Each scalar setting above is settable via `pm config set <key> <value>` (no hand-editing of `settings.json`). The dotted `settings.json` path is shown in parentheses where it differs from the CLI key:
+
+```bash
+pm config project set id_prefix task                       # (id_prefix) IDs become task-xxxx
+pm config project set author_default release-bot           # (author_default) default mutation author
+pm config project set output_default_format json           # (output.default_format) toon | json
+pm config project set locks_ttl_seconds 60                 # (locks.ttl_seconds) integer >= 1
+pm config project set schema_unknown_field_policy reject   # (schema.unknown_field_policy) allow | warn | reject
+```
+
 ## Environment Variables
 
 | Variable | Use |
@@ -353,6 +363,79 @@ pm contracts --json
 pm create --help --type Task
 ```
 
+## Custom Runtime Fields
+
+Custom runtime fields add typed flags to `pm create`/`pm update` (and optionally `list`/`search`/`context`) and persist their values into item metadata. They are the most powerful customization primitive: a field defined here becomes a first-class `--flag` with validation, completions, and `--help` text, with no code changes.
+
+> The preferred way to add a field is the CLI — `pm schema add-field` writes a well-formed entry for you and validates collisions. Hand-authoring `schema/fields.json` (below) is equivalent and useful for bulk edits or version-controlled review.
+
+Fields live in `.agents/pm/schema/fields.json` with the shape `{ "fields": [RuntimeFieldDefinition...] }`:
+
+```jsonc
+// .agents/pm/schema/fields.json
+{
+  "fields": [
+    {
+      "key": "component",                 // required: canonical field name (snake_case)
+      "type": "string",                   // string | number | boolean | string_array (default string)
+      "metadata_key": "component",        // item metadata key (defaults to `key`)
+      "cli_flag": "component",            // long flag, used as --component (defaults to key)
+      "cli_aliases": ["comp"],            // extra accepted flag spellings (--comp)
+      "commands": ["create", "update", "list"], // create | update | update_many | list | search | calendar | context
+      "description": "Owning component",  // shown in --help
+      "required": false,                  // required on every mutation when true
+      "required_on_create": false,        // required only on create
+      "allow_unset": true,                // allow clearing via --component "" / --no-component
+      "required_types": ["Task"]          // only required for these item types (subset of required*)
+    }
+  ]
+}
+```
+
+`RuntimeFieldDefinition` properties:
+
+- `key` (**required**) — canonical field name. Empty/invalid keys are dropped.
+- `type` — `string` (default), `number`, `boolean`, or `string_array`. A `string_array` field is repeatable (accepts the flag multiple times).
+- `metadata_key` — the item metadata key written/read. Defaults to `key`.
+- `cli_flag` — the long flag name (rendered as `--<cli_flag>`). Defaults to a normalized form of `key`.
+- `cli_aliases` — additional flag spellings; duplicates of `cli_flag` are ignored.
+- `commands` — which commands expose the flag. Defaults to `["create", "update"]`.
+- `required` — value must be present on every accepted mutation.
+- `required_on_create` — value must be present on `pm create` (but not on later updates).
+- `allow_unset` — when `true` (default), the field can be cleared; when `false`, an explicit unset is rejected.
+- `required_types` — narrows `required`/`required_on_create` to only the listed item types.
+- `description` — surfaced in `--help`.
+
+End-to-end example — add a required-on-create `component` string field on `Task` items:
+
+```jsonc
+// .agents/pm/schema/fields.json
+{
+  "fields": [
+    {
+      "key": "component",
+      "type": "string",
+      "cli_flag": "component",
+      "commands": ["create", "update", "list"],
+      "description": "Owning component (auth, billing, ...).",
+      "required_on_create": true,
+      "required_types": ["Task"]
+    }
+  ]
+}
+```
+
+```bash
+pm create Task "Fix token refresh" --component auth   # stored in item metadata
+pm list --component auth                              # filter by the custom field
+```
+
+**Governance note:** how item I/O treats metadata keys that are not in the field registry is controlled by `schema.unknown_field_policy` — `allow` (default, keeps unknown keys), `warn` (keeps them but emits a warning), or `reject`. Set `reject` to catch field-name typos once your field registry is stable:
+
+```bash
+pm config project set schema_unknown_field_policy reject   # allow | warn | reject
+```
+
 ## Public Documentation Boundary
 
 Public docs should describe supported user configuration only. Ignored local operations material, unpublished evidence logs, credentials, hostnames, and private service details must stay outside tracked docs and package output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.16",
+  "version": "2026.6.17",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",

package/dist/cli-bundle/chunks/activity-5P2KQCTH.js

@@ -1,18 +0,0 @@
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-OCTQJP42.js";
-import "./chunk-2IUJBMKS.js";
-import "./chunk-ZJRDVYZI.js";
-import "./chunk-7AGIXLNK.js";
-import "./chunk-4KBK4BA3.js";
-import "./chunk-WZCQVABQ.js";
-import "./chunk-GYMG7AG6.js";
-import "./chunk-6BV7ENQL.js";
-import "./chunk-OY3P2I6B.js";
-import "./chunk-LV5FFQ7M.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-5P2KQCTH.js.map