@aopslabs/aops 0.3.31 → 0.3.32

package/aops-assets-release/skills/aops-cli-fileman/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: aops-cli-fileman
+version: 7
+description: "Use when an AI agent needs AOPS CLI Fileman operator playbook: target tracking, snapshot/file lineage, diff/restore/copy/zip, clean, and content-pointer-only owner boundary. Thin guide; command --help and domains/fileman/USER_GUIDE.md are authoritative."
+metadata:
+  supersedes: "v6"
+  short-description: "AOPS CLI Fileman thin discipline guide"
+  tags:
+    - cli
+    - fileman
+    - snapshot
+    - diff
+    - restore
+    - copy
+    - backup
+    - target
+    - retention
+    - help-first
+---
+
+# AOPS CLI Fileman
+
+Fileman owns filesystem target tracking, immutable snapshots, file lineage, restore/copy/zip exports, and cleanup. `aops-cli file ...` is only the operator sugar surface. When this skill conflicts with live `--help` or `domains/fileman/USER_GUIDE.md`, those win.
+
+## Use This Skill For
+
+1. Track a directory root and capture a baseline snapshot.
+2. Create/list/get/diff/rebase/restore/copy/zip snapshots.
+3. Read file history, file content, file diffs, and single-file restore/extract.
+4. Clean stale Fileman state through the hosted graph.
+5. Decide when to use a Fileman pointer instead of pasting content into PM, Docman, or memory.
+
+Use `aops-cli-core` for guard flags and schema fallback; use `aops-cli-docman` for document content; use `aops-cli-agentspace` for memory/resource/artifact/skill surfaces.
+
+## Authoritative Sources
+
+1. Live command shape:
+   - `aops-cli file --help`
+   - `aops-cli file target --help`
+   - `aops-cli file target track --help`
+   - `aops-cli file snapshot --help`
+   - `aops-cli file file --help`
+   - `aops-cli file clean --help`
+2. Domain semantics: `domains/fileman/USER_GUIDE.md` and `domains/fileman/architecture.md`.
+3. Raw hosted contracts only when sugar is insufficient: `aops-cli agent schema --tool fileman.<operation> --json`.
+
+There is no default `.aops/fileman/**` authoring mirror. Fileman is hosted-canonical; the repo normally stores only references to Fileman ids or storage pointers.
+
+## Live Command Map
+
+| Need | Command |
+|---|---|
+| Track a root and baseline snapshot | `aops-cli file target track --root-path <dir> --apply --json` |
+| Orient before mutation | `aops-cli file inspect target --target-id <id> --json`; for one file use `aops-cli file inspect file --target-id <id> --path <rel> --json` |
+| Read target inventory | `aops-cli file target list|get` |
+| Create/list/get snapshots | `aops-cli file snapshot create|list|get` |
+| Diff snapshots | Prefer `aops-cli file snapshot diff --from-snapshot-id <older> --to-snapshot-id <newer>`; use `--target-id <id>` only when Fileman's default pair/direction is acceptable |
+| Rebase baseline | `aops-cli file snapshot rebase --target-id <id> --dry-run --preview` then `--apply --confirm` |
+| Restore snapshot tree | `aops-cli file snapshot restore --snapshot-id <id> --dry-run`, then `--apply --confirm` |
+| Copy snapshot tree | `aops-cli file snapshot copy --target-id <id> --output-path <dir> --apply` |
+| Zip snapshot tree | `aops-cli file snapshot zip --target-id <id> --output-path <staging> --zip-path <zip> --apply` |
+| File history | `aops-cli file file history --target-id <id> --path <rel>` |
+| File content | `aops-cli file file get --snapshot-id <snapshot-id> --path <rel>` |
+| File diff | `aops-cli file file diff --from-file-version-id <a> --to-file-version-id <b>` |
+| Restore one file | `aops-cli file file restore --target-id <id> --path <rel> --dry-run`, then `--apply --confirm` |
+| Cleanup | `aops-cli file clean --target-id <id> --dry-run --preview`, then `--apply --confirm` |
+
+Important correction: live CLI nests diff/restore/copy/zip under `file snapshot ...` and single-file operations under `file file ...`. Do not use stale top-level shapes such as `aops-cli file restore` or `aops-cli file diff`.
+
+## Root Path Rule
+
+`file target track --root-path` tracks a directory root. If the operator gives a single file, track its parent directory and use the file-relative path through `file file ...`:
+
+```bash
+aops-cli file target track --name "<anchor>" --root-path "<parent-dir>" --apply --json
+aops-cli file file history --target-id <target-id> --path "<relative/file.ext>" --json
+```
+
+Current CLI/server guard rejects non-directory roots with `target_path_not_directory:<path>`.
+
+## Common Workflows
+
+Safety shorthand: `--preview` validates the hosted mutation envelope; `--dry-run` is Fileman domain input that previews filesystem or cleanup effects. For destructive restore/rebase/clean, run dry-run first, then rerun with `--apply --confirm` only after reviewing the plan.
+
+### Track And Snapshot
+
+```bash
+aops-cli file target track --name "<anchor>" --root-path "<absolute-dir>" \
+  --tag "<tag>" --label "<baseline label>" --message "<why>" \
+  --apply --yes --json
+
+aops-cli file snapshot create --target-id <target-id> \
+  --label "<checkpoint>" --message "<why>" --apply --json
+```
+
+For JSON handoff, read ids from `result.data.targetId`, `result.data.snapshotId`, or the mirrored `artifacts.targetId` / `artifacts.snapshotId` convenience fields. Do not assume nested `snapshot.id`; Fileman snapshot DTOs expose `snapshotId`.
+
+### Diff And Restore
+
+```bash
+aops-cli file snapshot diff --target-id <target-id> --json
+aops-cli file snapshot diff --from-snapshot-id <base> --to-snapshot-id <head> --json
+
+aops-cli file snapshot restore --snapshot-id <snapshot-id> --dry-run --json
+aops-cli file snapshot restore --snapshot-id <snapshot-id> \
+  --backup-before-restore --apply --confirm --json
+```
+
+For chronological diffs, prefer explicit older-to-newer ids. `file snapshot diff --target-id` lets Fileman pick the pair and direction, which may be surprising when an agent expects an addition-style patch.
+
+### Copy Or Zip For Handoff
+
+```bash
+aops-cli file snapshot copy --target-id <target-id> --snapshot-id <snapshot-id> \
+  --output-path "<output-dir>" --apply --json
+
+aops-cli file snapshot zip --target-id <target-id> --snapshot-id <snapshot-id> \
+  --output-path "<staging-dir>" --zip-path "<archive.zip>" --apply --json
+```
+
+### Single-File Recovery
+
+```bash
+aops-cli file file history --target-id <target-id> --path "<relative/file.ext>" --json
+aops-cli file file get --snapshot-id <snapshot-id> --path "<relative/file.ext>" --json
+aops-cli file file diff \
+  --from-file-version-id <base-file-version-id> \
+  --to-file-version-id <head-file-version-id> --json
+
+aops-cli file file restore --target-id <target-id> --path "<relative/file.ext>" \
+  --snapshot-id <snapshot-id> --dry-run --json
+aops-cli file file restore --target-id <target-id> --path "<relative/file.ext>" \
+  --snapshot-id <snapshot-id> --backup-before-restore --apply --confirm --json
+```
+
+`file file history` returns `result.data.versions[]`; use each row's `fileVersionId` for `file file diff`. `file file get` uses `--snapshot-id` + `--path`; it does not take `--target-id`.
+
+### Cleanup
+
+```bash
+aops-cli file clean --target-id <target-id> --dry-run --preview --json
+aops-cli file clean --target-id <target-id> --missing-only --apply --confirm --json
+```
+
+`--dry-run` is cleanup input, not the command guard. Pair it with `--preview` to inspect cleanup without mutation. To remove a temporary tracked target, make the root missing or target a missing root, then run `file clean --target-id <id> --missing-only --apply --confirm --json`. Fileman does not currently expose `file target delete` or `file target untrack` sugar.
+
+Use `file clean` instead of manually deleting snapshot files; manual deletion can break hosted graph consistency.
+
+## Deep Reading
+
+Use targeted reads, not full dumps:
+
+```bash
+aops-cli doc scope search --project-slug aops --q "fileman snapshot restore" --local --json
+aops-cli doc search --document-version-id <docver-id> --q "restore" --local --json
+aops-cli view doc-page <document-slug>#<section-slug> --max-bytes 6000
+aops-cli doc outline get --document-version-id <docver-id> --titles-only --depth 2 --json
+```
+
+`doc scope search` is broad and can rank source docs above guide docs. `doc search --local` is retrieval/search, not a guaranteed full section-body reader. Use `view doc-page` when you need the actual mirrored section body. There is no `aops-cli docman ... --slug` command.
+
+## Anti-Patterns
+
+1. Guessing stale top-level commands instead of live nested help.
+2. Tracking a single file as `--root-path`; track the parent directory and use relative file operations.
+3. Treating live path state as snapshot history; snapshots are immutable history and live state may drift.
+4. Embedding large file bodies into memory/PM/Docman instead of referencing Fileman target/snapshot/file-version ids.
+5. Restoring without dry-run and explicit `--apply --confirm`.
+6. Manually deleting snapshot storage instead of `aops-cli file clean`.

package/aops-assets-release/skills/aops-cli-mission/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: aops-cli-mission
+version: 3
+description: "Use when an AOPS agent needs hosted Agentspace mission command discipline: create/list/get/update/resume, mission.policy seed via --policy-json, active Projectman implementation-plan ref, start --resume integration, and mission vs Projectman/memory ownership boundaries."
+metadata:
+  short-description: "AOPS CLI mission command guide"
+  tags:
+    - aops
+    - cli
+    - mission
+    - agentspace
+    - policy
+    - resume
+    - start
+---
+
+# AOPS CLI Mission
+
+Use this skill when a task involves `aops-cli mission ...`, mission policy,
+mission resume packs, or the mission/start bridge.
+
+If this skill conflicts with `aops-cli mission --help`, `aops-cli start --help`,
+or the Agentspace User Guide, those sources win.
+
+## Ownership
+
+Mission is Agentspace-owned durable intent and policy.
+
+Projectman remains execution and review truth:
+
+- kanban task
+- sprint-backed implementation plan
+- microtasks
+- issues
+- review requests and RRR
+
+Memory remains durable carry-forward context. Chat remains coordination/wake.
+Discuss remains material decision truth.
+
+## Command map
+
+| Need | Command |
+| --- | --- |
+| Create mission | `aops-cli mission create --objective "<text>" --policy-json '<json>' --apply --json` |
+| List missions | `aops-cli mission list --summary --json` |
+| Read one mission | `aops-cli mission get --id <id> --json` |
+| Patch mission | `aops-cli mission update --id <id> --policy-json '<json>' --apply --json` |
+| Resume mission | `aops-cli mission resume --id <id> --depth light --limit 8 --json` |
+| Start from mission | `aops-cli start --resume <mission-id> --mode <mode> --board <board> --json` |
+| Mid-session reminder | `aops-cli start --reminder --task "<current task>" --area <area> --json` |
+
+Run live help before unfamiliar flags:
+
+```bash
+aops-cli mission --help
+aops-cli mission create --help
+aops-cli mission resume --help
+aops-cli start --help
+```
+
+## Policy seed
+
+`aops-cli start --json` emits:
+
+- `result.mission.discipline`
+- `result.mission.guardrails`
+- `result.mission.policy`
+- `result.mission.policyJson`
+- `result.mission.startPack.policySeed`
+
+Current policy seeds conventionally include these top-level groups:
+
+- `discipline`
+- `signalMapping`
+- `guardrails`
+- `review`
+- `issue`
+- `memory`
+- `plan`
+- `planning`
+- `orchestration`
+- `vocabBridge`
+
+Use `policyJson` with mission create/update:
+
+```bash
+aops-cli mission create --objective "<objective>" --policy-json '<result.mission.policyJson>' --apply --json
+aops-cli mission update --id <mission-id> --policy-json '<result.mission.policyJson>' --apply --json
+```
+
+The policy convention is documented in Docman guide "AOPS Working Disciplines"
+and the `aops-working-disciplines` skill. It is advisory and free-form, not a
+typed mission schema yet.
+
+## Active plan ref
+
+`--active-plan <sprint-id>` stores the active Projectman implementation-plan ref.
+The plan id is the underlying sprint id.
+
+Do not create a second mission-local plan model.
+
+## Resume discipline
+
+Default resume is compact and token-efficient:
+
+```bash
+aops-cli mission resume --id <mission-id> --json
+aops-cli start --resume <mission-id> --json
+```
+
+The compact pack includes mission identity/status, active Projectman plan refs,
+bounded PM/review/issue/memory refs, and the shared `sessionGuidance` pack.
+Use `--full` only when the raw hosted skeleton is truly needed. For a running
+session that only needs rules/playbook/experience refresh, use
+`aops-cli start --reminder --task "<current task>" --area <area> --json`;
+that path is read-only and does not mutate the mission.
+
+## Boundaries and anti-patterns
+
+1. Do not store task progress only in mission body or policy; Projectman owns
+   execution truth.
+2. Do not invent a mission handoff command in this slice; use Projectman handoff
+   or `aops-cli mem summary`.
+3. Do not use mission policy as a typed enum yet. It is free-form with the
+   working-discipline convention.
+4. Do not claim future mission helpers exist until live `aops-cli mission --help`
+   exposes them. Use PM/RR/memory evidence today.
+5. Do not hand-edit hosted mirrors after mission/skill/doc changes.

package/aops-assets-release/skills/aops-cli-operator-brief/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: aops-cli-operator-brief
+version: 3
+description: "Use when an AI agent needs to summarize AOPS PM, memory, discussion, or collab history in plain non-technical language for an operator asking what happened, what works, what was decided, or what remains open."
+metadata:
+  prompt-ref: "prompt:aops-operator-status-brief"
+  supersedes: "v2"
+  short-description: "Plain-language AOPS status summary guide"
+  tags:
+    - aops
+    - summary
+    - operator-brief
+    - projectman
+    - agentspace
+    - discuss
+    - collab
+---
+
+# AOPS Operator Brief
+
+Use this skill when the operator asks for a plain-language status summary of a mentioned AOPS subject: a task, sprint, board, memory thread, discussion topic, (historical) collab session, bug, feature, or "what did we do earlier?" style request.
+
+The canonical reusable prompt is `prompt:aops-operator-status-brief`. Use that prompt's source priority and output rules.
+
+## Read Order
+
+1. Parse the operator's wording and extract topic keywords or ids.
+2. Start with PM views:
+   - `aops-cli view dashboard --style agent`
+   - `aops-cli view task <selector>`
+   - `aops-cli view sprint <selector>`
+   - `aops-cli view digest --task|--sprint|--board <selector> --depth deep`
+3. Read memory records in this priority:
+   - closeout
+   - durable decision
+   - handoff or resume checkpoint
+   - kickoff
+4. Read session records only after PM/memory gives the right ids:
+   - `aops-cli discuss get <id> --json`
+   - Historical collab session records, if any, are read-only files under `.aops/agentspace/collabs/**` (the `aops-cli collab get` command is retired — read the files directly).
+5. Read review issues, feedback, commit summaries, logs, or browser proof only when they answer the operator's exact question.
+
+## Briefing Discipline
+
+- Write for the operator, not for the codebase.
+- Lead with what worked, what changed, and what decision was made.
+- Translate technical terms:
+  - `cwd` -> selected repo / working folder
+  - `threadId` -> Codex's local conversation handle
+  - `pm review-result` (or a historical `collab review-result` record) -> reviewer checked it
+  - `closeout` -> the work was closed with approval
+- Keep ids as follow-up handles, not as the main story.
+- If the operator asks "can we use Codex's own session?", answer in product terms: same-machine hint is okay; cross-machine native resume is not assumed.
+- If there is a browser/desktop split, say which mode supports which behavior.
+
+## Output
+
+Use short Turkish bullets. Prefer sections like:
+
+- Genel durum
+- Kullanici gozuyle ne yapildi
+- Calisiyor muydu
+- Kararlar
+- Kalanlar
+- Kaynaklar
+
+Avoid long technical explanations unless the operator explicitly asks.

package/aops-assets-release/skills/aops-cli-projectman/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: aops-cli-projectman
+version: 19
+description: "Use when an AI agent needs the AOPS CLI Projectman playbook: server-canonical boards, tasks, sprints, microtasks, issues, feedback, review requests/results/re-reviews, status audit, and PM-bound handoff."
+metadata:
+  supersedes: "v18"
+  short-description: "AOPS CLI Projectman thin discipline guide"
+  tags:
+    - cli
+    - projectman
+    - planning
+    - kanban
+    - sprint
+    - issue
+    - feedback
+    - review-request
+    - handoff
+    - server-canonical
+    - help-first
+---
+
+# AOPS CLI Projectman
+
+Projectman owns execution truth: boards, tasks, sprint plans, microtask status,
+issues, feedback, and canonical review requests/results.
+
+This is a thin agent guide. Exact flags live in `aops pm ... --help`; normative
+workflow lives in the current `Projectman User Guide`; the running server schema
+wins for raw hosted payloads.
+
+## Start Here
+
+1. Run `aops host health --json`.
+2. Run `aops project links list --json` and choose the intended project.
+3. Start with a bounded resume/inventory read, not a full unfiltered dump.
+4. Read the exact record and nested `--help` before a write.
+5. Use `--preview` where supported, then `--apply`; delete needs
+   `--apply --confirm`.
+6. Treat `.aops/projectman/**` as a read-only derived cache.
+
+The installed launcher may be `aops`; the package launcher is `aops-cli`.
+
+`--limit` on `pm issue list` and `pm feedback list` requires a CLI build newer
+than `@aopslabs/aops` 0.3.31. Installed 0.3.31 rejects that flag; until the next
+CLI release, omit it or use the repository-built CLI. Their response envelope
+always stores records in `data` alongside `count`, `shown`, and `hasMore`.
+
+## Use This Skill For
+
+- board and column lifecycle;
+- kanban tasks and sprint/microtask plans;
+- issues and feedback;
+- review request, append-only result, and child re-review records;
+- completion/review-scope audit and reconciliation;
+- Projectman-bound cross-session handoff.
+
+Use `aops-cli-discuss` for design consensus, `aops-cli-docman` for canonical
+written knowledge, `aops-cli-agentspace` for durable memory, and
+`aops-cli-chat` for coordination/wake.
+
+## Canonical Sources
+
+1. Hosted `Projectman User Guide` in `slug:aops`, group `domain-guides`,
+   document `0683979e-8b57-4632-8f88-e021b19ec70c`, current version
+   `99d3b4f8-c6aa-4ca8-9fe5-4751bc06a3a9`.
+2. Repo mirror:
+   `.aops/docman/domain-guides/projectman-user-guide.md` (read-only).
+3. Domain-development source: `domains/projectman/USER_GUIDE.md`.
+4. Exact flags: `aops pm --help` and the smallest nested `--help`.
+5. Raw tool discovery: `aops agent tools --domain projectman --summary --json`
+   and `aops agent schema --tool <tool-id> --summary --json`.
+
+When this skill and help disagree, help wins for flags. When this skill and the
+guide disagree, the published current guide wins for workflow.
+
+## Workflow 0: Select the Project Partition
+
+```bash
+aops project links list --json
+aops pm resume --project-slug <slug> --for <agent-id> --limit 10 --json
+```
+
+Always pass `--project-slug` for a material write when more than one hosted
+project is linked. The local link resolves the destination; the hosted server
+record remains canonical.
+
+## Retrieval Ladder
+
+Use the smallest useful surface:
+
+1. compact context:
+
+   ```bash
+   aops pm resume --project-slug <slug> --for <agent-id> --limit 10 --json
+   ```
+
+2. bounded inventories:
+
+   ```bash
+   aops pm sprint list --project-slug <slug> --status doing --limit 10 --summary --json
+   aops pm issue list --project-slug <slug> --status open --limit 10 --json
+   aops pm feedback list --project-slug <slug> --status new --limit 10 --json
+   ```
+
+3. exact record:
+
+   ```bash
+   aops pm sprint get --project-slug <slug> --id <sprint-id> --json
+   ```
+
+4. status truth:
+
+   ```bash
+   aops pm status audit --project-slug <slug> --task <task-id> --json
+   ```
+
+5. deep guide search:
+
+   ```bash
+   aops doc search --document-version-id 99d3b4f8-c6aa-4ca8-9fe5-4751bc06a3a9 --q "<question>" --json
+   aops doc answer --document-version-id 99d3b4f8-c6aa-4ca8-9fe5-4751bc06a3a9 --q "<question>" --json
+   ```
+
+## Model
+
+1. Board = long-lived work stream.
+2. Kanban task = operator-visible unit of work.
+3. Sprint = bounded execution window.
+4. Phase = grouped section inside a sprint.
+5. Microtask = smallest explicit status/evidence owner.
+6. Issue = concrete defect, risk, or blocker.
+7. Feedback = observation or improvement signal.
+8. Review request = canonical review record; results are append-only entries.
+
+## Workflow 1: Multi-Step Sprint
+
+```bash
+aops pm ktask create --project-slug <slug> --board <board> --column todo \
+  --title "<semantic task>" --apply --json
+
+aops pm sprint create --project-slug <slug> --task <task-id> \
+  --name "<semantic sprint>" \
+  --goal "NE: <work>; NICIN: <why>; DONE-WHEN: <acceptance>" \
+  --reference discuss:<topic-id> --apply --json
+
+aops pm sprint update-plan --project-slug <slug> --id <sprint-id> \
+  --phases-json '@./plan.json' --apply --json
+
+aops pm utask update --project-slug <slug> --sprint <sprint-id> \
+  --id <utask-id> --status completed --notes "<evidence>" --apply --json
+```
+
+Read the current sprint first. Use `--expected-updated-at` for a full plan edit
+when concurrent work is possible. Prefer `utask update` for one microtask.
+
+## Workflow 2: Review and Re-Review
+
+```bash
+aops pm review-request create --project-slug <slug> --task <task-id> \
+  --sprint <sprint-id> --title "<review>" --target-agent <reviewer> \
+  --review-scope "sprint:<sprint-id>" --instructions "<checks>" --apply --json
+
+aops pm review-request result --project-slug <slug> --id <rr-id> \
+  --reviewer <reviewer> --outcome changes_requested \
+  --summary "<finding summary>" --issue <issue-id> --apply --json
+
+aops pm issue create --project-slug <slug> --source review \
+  --review-request <rr-id> --title "<material finding>" \
+  --severity high --apply --json
+
+aops pm review-request create --project-slug <slug> --parent <rr-id> \
+  --title "<re-review>" --target-agent <reviewer> \
+  --review-scope "sprint:<sprint-id>" --apply --json
+```
+
+Chat may announce the outcome; Projectman RR/status/result id is canonical.
+
+## Workflow 3: Cross-Session Handoff
+
+```bash
+aops pm handoff write --project-slug <slug> --mode resume \
+  --subject sprint --id <sprint-id> --content "<state and next action>" \
+  --apply --json
+
+aops pm handoff resume --project-slug <slug> --subject sprint \
+  --id <sprint-id> --strict-subject --json
+```
+
+Use `aops mem write` directly when no real Projectman subject exists. Do not
+create a fake task solely to hold narrative memory.
+
+## Always Rules
+
+1. Always author Projectman through the hosted gateway; never hand-edit
+   `.aops/projectman/**`.
+2. Always select the intended project explicitly when multiple links exist.
+3. Always read nested `--help`; fetch live JSON Schema before raw invoke or
+   sugar implementation.
+4. Always use write guards: `--preview`, then `--apply`; destructive operations
+   require `--apply --confirm` and explicit authority.
+5. Never run `pm board closeout` automatically; it is an operator decision.
+6. Remember `pm sprint set-status` rewrites all nested microtasks; use
+   `pm utask update` for granular evidence.
+7. Keep RR/RRR canonical in Projectman and create/link every material review
+   finding explicitly as an issue.
+8. Keep Projectman thin; durable narrative context belongs in Agentspace
+   memory, while PM holds scope, status, refs, acceptance, and short evidence.
+9. Use semantic titles and `NE`, `NICIN`, `DONE-WHEN`; bind material Discuss
+   consensus to the plan and obtain the required plan RR before implementation.
+
+## Top Anti-Patterns
+
+- broad unfiltered list reads when a bounded/filterable read is enough;
+- opaque codes as operator-facing titles;
+- a phase with no microtask;
+- replacing a full plan to update one microtask;
+- treating chat acknowledgement as review approval;
+- overwriting a changes-requested RR instead of opening a child RR;
+- using local cache edits to repair hosted state;
+- creating duplicate issues without checking exact existing records.
+
+## Troubleshooting
+
+- Wrong project: stop, inspect links, rerun with `--project-slug`.
+- Undeclared input rejected: inspect `agent schema`; keep client-only fields out
+  of the hosted payload.
+- `hasMore: true`: raise positive `--limit` or narrow server filters, then use
+  exact `get`.
+- Plan ids changed: stop full-plan writes; read current sprint and use narrow
+  microtask CRUD.
+- Every microtask status changed: `sprint set-status` is bulk by design.
+- Chat says approved but PM does not: read the canonical RR and result ids.
+- Mirror disagrees: hosted state wins; refresh through supported sync/pull.
+
+For full recipes and known exact issue ids, search the current guide.