@groeponline/pi-wishcraft 1.16.0 → 1.17.0

package/AGENTS.md

@@ -322,3 +322,13 @@ scripts/docker-test.sh -n 4   # 4 parallel containers
 ```
 
 Each container runs `typecheck + test + circular` with a shared read-only `node_modules` bind mount.
+
+## Agent skills
+
+### Issue tracker
+
+Dual-tracker: Linear for planning/features, GitHub for bugs/triage. See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context. Current domain source: AGENTS.md. CONTEXT.md and docs/adr/ to be added via `/domain-modeling` when needed. See `docs/agents/domain.md`.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-10-27
+
+### Fixed
+- Bash paste-while-running (issue #72): a bracketed paste performed while a command runs is stripped of its markers and forwarded to the child stdin — including split delivery across input chunks — instead of silently queuing in the editor buffer behind the command.
+- PTY/transcript memory bounds (from jan `fix/runtime-pty-bounds`): a single unterminated output line is capped at a 64 KiB UTF-8 tail with a one-time notice, the partial-escape tail is bounded, and the active transcript command trims head lines/bytes within limits instead of growing unbounded.
+- Segment-options spread hygiene (CodeFactor #86–89): `normalizeSegmentOptions` assigns fields imperatively instead of spreading conditional empty objects.
+
 ## [1.16.0] - 2026-10-03
 
 ### Known limitations

package/build-stamp.json

@@ -1 +1 @@
-{"source_sha":"1957ea6e4334e28e25770cba4114e33c69062632"}
+{"source_sha":"0c1a77045865dbb0dd6138ac1d0b381c067d0395"}

package/docs/agents/domain.md

@@ -0,0 +1,60 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`AGENTS.md`** at the repo root — the current domain documentation source with architecture, data flow, and conventions.
+- **`CONTEXT.md`** at the repo root, if it exists (currently absent).
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If `CONTEXT.md` or `docs/adr/` don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (this repo):
+
+**Current state:**
+- `AGENTS.md` — Primary domain documentation (architecture, data flow, conventions)
+- `docs/` — Operator guides and design specs (no ADRs currently)
+- `CONTEXT.md` — Not yet created (add via `/domain-modeling` when needed)
+
+**Target state (when CONTEXT.md exists):**
+
+```
+/
+├── AGENTS.md
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `AGENTS.md` (current domain source) or `CONTEXT.md` (if it exists). Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,88 @@
+# Issue tracker: Linear + GitHub
+
+This repo uses a dual-tracker workflow:
+- **Linear**: Long-term planning, roadmap, feature tracking
+- **GitHub**: Bug reports, PR-linked issues, immediate triage
+
+## Conventions
+
+### GitHub (primary for bugs and triage)
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+### Linear (for planning and features)
+- **Create a ticket**: `linear issue create --title "..." --description "..." --team <team-id>`. Use `linear teams list` to find team IDs.
+- **Read a ticket**: `linear issue view <ticket-id>` or `linear issue search --query "<title>"`.
+- **List tickets**: `linear issue list --team <team-id> --state <state>` with appropriate filters (e.g., `--state Backlog`, `--state In Progress`).
+- **Comment on a ticket**: `linear comment create <ticket-id> --body "..."`
+- **Change state**: `linear issue update <ticket-id> --state <state>`
+- **Assign**: `linear issue update <ticket-id> --assignee <user-id>`
+- **Link to GitHub**: Add a GitHub issue URL in the Linear ticket description, or use Linear's GitHub integration if configured.
+
+Use Linear for feature planning, roadmap items, and long-term tracking. Reference Linear tickets in GitHub issue bodies when applicable. Link GitHub PRs to related Linear tickets for traceability.
+
+### Linear conventions
+
+**Labels** (create in Linear):
+- `type:feature` — New features or enhancements
+- `type:bug` — Bugs that belong in the roadmap (not urgent)
+- `type:refactor` — Technical debt or architectural work
+- `type:research` — Investigation or exploration tasks
+- `priority:high` / `priority:medium` / `priority:low` — Priority levels
+
+**States** (use Linear's default workflow or customize):
+- `Backlog` — Planned but not started
+- `In Progress` — Active work
+- `In Review` — Awaiting review
+- `Done` — Completed
+- `Canceled` — Declined or superseded
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,comments` then fetch `authorAssociation` per PR with `gh api repos/:owner/:repo/pulls/<number> --jq '.author_association'` (the `gh pr list --json` field set does not include `authorAssociation`), keeping only `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+**Use GitHub when:**
+- Bug reports or regressions
+- Urgent issues requiring immediate triage
+- PR-linked issues or feedback from code review
+- Questions or clarifications about implementation
+
+**Use Linear when:**
+- Feature proposals or enhancements
+- Roadmap items or long-term planning
+- Research tasks or investigations
+- Technical debt or architectural refactoring
+- Multi-step work that benefits from project tracking
+
+If unsure, default to GitHub for bugs/immediate work, Linear for features/planning.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments` for GitHub issues. For Linear tickets, use the Linear CLI or API.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single Linear ticket with **child** tickets as tasks.
+
+- **Map**: a single Linear ticket labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `linear issue create --title "Map: <topic>" --description "..." --team <team-id> --label wayfinder:map`.
+- **Child ticket**: a Linear ticket linked to the map as a parent using Linear's parent-child relationship. Add the child to the map's sub-issues and put `Part of <map-id>` at the top of the child description. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: Use Linear's **native issue dependencies**. Add a blocker with `linear issue update <child> --blocking <blocker-id>`. Linear reports blocking status in the UI. A ticket is unblocked when every blocker is resolved.
+- **Frontier query**: list the map's open children (`linear issue list --team <team-id> --parent <map-id> --state Backlog,In Progress`), drop any with an open blocker or an assignee; first in map order wins.
+- **Claim**: `linear issue update <ticket-id> --assignee @me`, the session's first write.
+- **Resolve**: `linear comment create <ticket-id> --body "<answer>"`, then `linear issue update <ticket-id> --state Done`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Pi coding agent extension: operator cockpit with a live powerline status bar, idea queue, skill search, sticky Bash, hooks, policy guardrails, and TUI session UX.",
   "type": "module",
   "engines": {

package/src/extension/core/peer-guard.ts

@@ -130,7 +130,7 @@ export function findMissingPeerSymbols(
 }
 
 /** The live peer namespaces, collected for the runtime check. */
-export function collectPeerExports(): Record<PeerPackage, unknown> {
+function collectPeerExports(): Record<PeerPackage, unknown> {
   return {
     "@earendil-works/pi-ai": piAi,
     "@earendil-works/pi-coding-agent": piCodingAgent,
@@ -166,7 +166,7 @@ export function formatPeerGuardNotice(
 }
 
 /** Actionable error for a call site that cannot degrade gracefully. */
-export function missingSymbolError(symbol: string): Error {
+function missingSymbolError(symbol: string): Error {
   const requirement = PEER_SYMBOL_REQUIREMENTS.find(
     (r) => r.symbol === symbol,
   );