@noice-tech/pi-changelog 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noice Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @noice-tech/pi-changelog
+
+A Pi package for release-aware commits, pull requests, unreleased previews, and public release notes.
+
+## Install
+
+```bash
+pi install npm:@noice-tech/pi-changelog
+```
+
+Commit the resulting `.pi/settings.json` change so Pi installs the package for collaborators.
+
+## Prerequisites and trust
+
+The workflows expect:
+
+- Git
+- [GitHub CLI](https://cli.github.com/) authenticated for the repository
+- Bash and `jq`
+- a shell that supports process substitution for the documented `gh api` PR-update flow
+
+Pi packages run with the permissions granted to Pi. **Only use this package when you trust it with full system permissions and repository access.** In particular, `/commit` inspects changes, creates commits, pushes branches, and creates or updates GitHub pull requests.
+
+## Commands
+
+```text
+/commit [auto|feat|fix|improve|internal] [optional context]
+/unreleased
+/release-notes <version | from..to>
+/setup-release-notes-style [product/audience/channel notes]
+```
+
+`auto` is accepted only as `/commit` inference input. Changelog and PR classifications are `feat`, `fix`, `improve`, or `internal`.
+
+The canonical shared classification rules live in `extensions/changelog/rules.md`.
+
+## Repository-specific release-note style
+
+Run `/setup-release-notes-style` to create or refine the only canonical repository-specific convention:
+
+```text
+.pi/release-notes-style.md
+```
+
+`/release-notes` reads that file when present. It otherwise emits a plain Markdown bullet list.
+
+## Release-note output
+
+`/release-notes 1.2.3` uses a deterministic slug and writes two separate files:
+
+- public copy: `release-notes/1.2.3.md`
+- private review sources: `.pi/tmp/pi-changelog/release-notes-sources/1.2.3.md`
+
+The public artifact never contains PR numbers, commit hashes, private URLs, or internal source notes. The `.pi/tmp/` source file is an ephemeral private-review aid. Keep `.pi/tmp/` ignored by Git and unpublished; the prompt does not edit a consumer repository's `.gitignore`.
+
+## Package contents
+
+The npm package distributes the Pi manifest together with raw TypeScript and Markdown extension/prompt assets. No build step is required.

package/extensions/changelog/index.ts

@@ -0,0 +1,498 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext
+} from '@earendil-works/pi-coding-agent'
+import { getMarkdownTheme } from '@earendil-works/pi-coding-agent'
+import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CHANGE_TYPES = ['auto', 'feat', 'fix', 'improve', 'internal'] as const
+type ChangeType = (typeof CHANGE_TYPES)[number]
+
+const CHANGE_TYPE_OPTIONS: Array<{ type: ChangeType; label: string }> = [
+  {
+    type: 'auto',
+    label: 'auto - Let commit worker infer from session and diff'
+  },
+  { type: 'feat', label: 'feat - New user-facing capability' },
+  { type: 'fix', label: 'fix - User-facing bug fix' },
+  {
+    type: 'improve',
+    label: 'improve - User-facing refinement/performance/reliability'
+  },
+  {
+    type: 'internal',
+    label: 'internal - Infra/tooling/tests/refactor/deps/logging'
+  }
+]
+
+const MESSAGE_TYPE = 'noice-changelog-commit-result'
+const PROMPT_MESSAGE_TYPE = 'noice-changelog-commit-worker-prompt'
+const STATUS_KEY = 'noice-changelog'
+
+type CommitDisplayStatus = 'ok' | 'cancelled' | 'failed'
+
+interface CommitResultDetails {
+  changeType?: ChangeType
+  userContext?: string
+  workerLeafId?: string | null
+  status?: CommitDisplayStatus
+}
+
+let commitWorkerRunning = false
+let agentEndWaiter: ((messages: unknown[]) => void) | undefined
+let latestCommitWorkerMessages: unknown[] | undefined
+
+export default function noiceChangelogExtension(pi: ExtensionAPI) {
+  pi.on('agent_end', (event) => {
+    if (commitWorkerRunning) {
+      latestCommitWorkerMessages = event.messages
+    }
+    agentEndWaiter?.(event.messages)
+    agentEndWaiter = undefined
+  })
+
+  pi.on('context', (event) => {
+    return {
+      messages: event.messages.filter((message) => {
+        const customType = (message as { customType?: string }).customType
+        if (customType === MESSAGE_TYPE) return false
+        if (customType === PROMPT_MESSAGE_TYPE && !commitWorkerRunning)
+          return false
+        return true
+      })
+    }
+  })
+
+  async function sendResultAtSourceLeaf(
+    ctx: ExtensionCommandContext,
+    sourceLeafId: string | null | undefined,
+    message: {
+      customType: string
+      content: string
+      display: boolean
+      details?: CommitResultDetails
+    }
+  ) {
+    // `agent_end` fires before the session has fully left streaming mode. If we
+    // send while streaming, pi treats this as steering/follow-up input instead
+    // of appending a visible custom message, so it may only show on the next
+    // user turn. Wait until idle before writing the result entry.
+    if (!ctx.isIdle()) {
+      await ctx.waitForIdle()
+    }
+
+    pi.sendMessage(message)
+
+    // Keep the result attached to the source point, but leave the active leaf
+    // at the original source so the next user message branches from there.
+    const currentLeafId = ctx.sessionManager.getLeafId()
+    if (sourceLeafId && currentLeafId && currentLeafId !== sourceLeafId) {
+      await ctx.navigateTree(sourceLeafId, { summarize: false })
+    }
+  }
+
+  pi.registerMessageRenderer<CommitResultDetails>(
+    MESSAGE_TYPE,
+    (message, _options, theme) => {
+      const details = message.details
+      const c = new Container()
+      const displayStatus = getDisplayStatus(
+        typeof message.content === 'string' ? message.content : '',
+        details?.status
+      )
+      const statusLabel =
+        displayStatus === 'cancelled'
+          ? theme.fg('warning', 'cancelled')
+          : displayStatus === 'failed'
+            ? theme.fg('error', 'failed')
+            : theme.fg('success', 'ok')
+
+      c.addChild(
+        new Text(
+          `${statusLabel} ${theme.fg('toolTitle', theme.bold('commit'))}${details?.changeType ? ` ${theme.fg('accent', details.changeType)}` : ''}`,
+          0,
+          0
+        )
+      )
+
+      if (details?.userContext) {
+        c.addChild(
+          new Text(theme.fg('dim', `Context: ${details.userContext}`), 0, 0)
+        )
+      }
+
+      c.addChild(new Spacer(1))
+      c.addChild(
+        new Markdown(
+          typeof message.content === 'string' ? message.content : '',
+          0,
+          0,
+          getMarkdownTheme()
+        )
+      )
+
+      if (details?.workerLeafId) {
+        c.addChild(new Spacer(1))
+        c.addChild(
+          new Text(
+            theme.fg('dim', `Worker branch: ${details.workerLeafId}`),
+            0,
+            0
+          )
+        )
+      }
+
+      return c
+    }
+  )
+
+  pi.registerCommand('commit', {
+    description:
+      'Commit changes and create/update PR. Usage: /commit <changeType> <what was done>',
+    getArgumentCompletions: getCommitArgumentCompletions,
+    handler: async (args, ctx) => {
+      if (commitWorkerRunning) {
+        ctx.ui.notify('Commit worker is already running', 'warning')
+        return
+      }
+
+      await ctx.waitForIdle()
+
+      const parsed = await resolveChangeTypeAndContext(args, ctx)
+      if (!parsed) {
+        return
+      }
+
+      const startLeafId = ctx.sessionManager.getLeafId()
+      const prompt = await buildWorkerPrompt(parsed.changeType, parsed.context)
+
+      commitWorkerRunning = true
+      ctx.ui.setStatus(STATUS_KEY, 'running in session branch...')
+      ctx.ui.notify(`Starting commit worker (${parsed.changeType})`, 'info')
+
+      try {
+        const agentEnd = waitForNextAgentEndAfterIdle(ctx)
+        latestCommitWorkerMessages = undefined
+        pi.sendMessage(
+          {
+            customType: PROMPT_MESSAGE_TYPE,
+            content: prompt,
+            display: false,
+            details: {
+              changeType: parsed.changeType,
+              userContext: parsed.context
+            }
+          },
+          { triggerTurn: true, deliverAs: 'followUp' }
+        )
+        const messages = await agentEnd
+
+        const workerLeafId = ctx.sessionManager.getLeafId()
+        const workerPromptIndex = findLastCustomMessageIndex(
+          messages,
+          PROMPT_MESSAGE_TYPE
+        )
+        const summary =
+          workerPromptIndex >= 0
+            ? extractLastAssistantText(messages, workerPromptIndex)
+            : ''
+        const assistantError =
+          workerPromptIndex >= 0
+            ? extractLastAssistantError(messages, workerPromptIndex)
+            : undefined
+
+        if (assistantError) {
+          if (startLeafId && workerLeafId && workerLeafId !== startLeafId) {
+            await ctx.navigateTree(startLeafId, { summarize: false })
+          }
+          await sendResultAtSourceLeaf(ctx, startLeafId, {
+            customType: MESSAGE_TYPE,
+            content: formatWorkerErrorResult(assistantError, summary),
+            display: true,
+            details: {
+              changeType: parsed.changeType,
+              userContext: parsed.context,
+              workerLeafId,
+              status: 'failed'
+            }
+          })
+          ctx.ui.notify(`Commit worker failed:\n${assistantError}`, 'error')
+          return
+        }
+
+        if (!summary) {
+          if (startLeafId && workerLeafId && workerLeafId !== startLeafId) {
+            await ctx.navigateTree(startLeafId, { summarize: false })
+          }
+          await sendResultAtSourceLeaf(ctx, startLeafId, {
+            customType: MESSAGE_TYPE,
+            content:
+              'status: cancelled\nnotes: Commit command was cancelled before the worker produced a result.',
+            display: true,
+            details: {
+              changeType: parsed.changeType,
+              userContext: parsed.context,
+              workerLeafId,
+              status: 'cancelled'
+            }
+          })
+          ctx.ui.notify('Commit command cancelled', 'warning')
+          return
+        }
+
+        if (startLeafId && workerLeafId && workerLeafId !== startLeafId) {
+          const nav = await ctx.navigateTree(startLeafId, { summarize: false })
+          if (nav.cancelled) {
+            pi.sendMessage({
+              customType: MESSAGE_TYPE,
+              content:
+                'status: cancelled\nnotes: Commit worker finished, but returning to the original branch was cancelled.',
+              display: true,
+              details: {
+                changeType: parsed.changeType,
+                userContext: parsed.context,
+                workerLeafId,
+                status: 'cancelled'
+              }
+            })
+            ctx.ui.notify(
+              'Commit finished, but tree navigation was cancelled',
+              'warning'
+            )
+            return
+          }
+        }
+
+        const displayStatus = getDisplayStatus(summary)
+        await sendResultAtSourceLeaf(ctx, startLeafId, {
+          customType: MESSAGE_TYPE,
+          content: summary,
+          display: true,
+          details: {
+            changeType: parsed.changeType,
+            userContext: parsed.context,
+            workerLeafId,
+            status: displayStatus
+          }
+        })
+        ctx.ui.notify(
+          formatCommitNotification(summary, displayStatus),
+          displayStatus === 'failed'
+            ? 'error'
+            : displayStatus === 'cancelled'
+              ? 'warning'
+              : 'info'
+        )
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        if (startLeafId)
+          await ctx.navigateTree(startLeafId, { summarize: false })
+        await sendResultAtSourceLeaf(ctx, startLeafId, {
+          customType: MESSAGE_TYPE,
+          content: `Commit worker failed: ${message}`,
+          display: true,
+          details: {
+            changeType: parsed.changeType,
+            userContext: parsed.context,
+            status: 'failed'
+          }
+        })
+        ctx.ui.notify(`Commit worker failed:\n${message}`, 'error')
+      } finally {
+        ctx.ui.setStatus(STATUS_KEY, undefined)
+        commitWorkerRunning = false
+        latestCommitWorkerMessages = undefined
+      }
+    }
+  })
+}
+
+function getCommitArgumentCompletions(prefix: string) {
+  const trimmedStart = prefix.trimStart()
+  const leadingWhitespace = prefix.slice(0, prefix.length - trimmedStart.length)
+  const [firstWord = ''] = trimmedStart.split(/\s+/)
+  const isTypingDescription = /^\S+\s/.test(trimmedStart)
+
+  if (!isTypingDescription) {
+    const matches = CHANGE_TYPE_OPTIONS.filter((option) =>
+      option.type.startsWith(firstWord)
+    )
+    return matches.length > 0
+      ? matches.map((option) => ({
+          value: `${leadingWhitespace}${option.type} `,
+          label: option.label
+        }))
+      : null
+  }
+
+  if (!isChangeType(firstWord)) return null
+
+  const whatWasDone = trimmedStart.slice(firstWord.length).trim()
+  return [
+    {
+      value: prefix,
+      label: whatWasDone
+        ? `What was done: "${whatWasDone}"`
+        : 'Say what was done — rough wording is fine; leave blank to infer from session/diff'
+    }
+  ]
+}
+
+async function resolveChangeTypeAndContext(
+  args: string | undefined,
+  ctx: ExtensionCommandContext
+): Promise<{ changeType: ChangeType; context: string } | null> {
+  const trimmedArgs = args?.trim() ?? ''
+  const [firstWord = '', ...rest] = trimmedArgs.split(/\s+/)
+
+  if (isChangeType(firstWord)) {
+    return { changeType: firstWord, context: rest.join(' ').trim() }
+  }
+
+  const selected = await ctx.ui.select(
+    'Change type',
+    CHANGE_TYPE_OPTIONS.map((option) => option.label)
+  )
+  if (!selected) return null
+
+  const option = CHANGE_TYPE_OPTIONS.find((item) =>
+    selected.startsWith(item.type)
+  )
+  if (!option) return null
+
+  return { changeType: option.type, context: trimmedArgs }
+}
+
+function isChangeType(value: string): value is ChangeType {
+  return CHANGE_TYPES.includes(value as ChangeType)
+}
+
+async function buildWorkerPrompt(changeType: ChangeType, userContext: string) {
+  const extensionDir = dirname(fileURLToPath(import.meta.url))
+  const [template, rules] = await Promise.all([
+    readFile(join(extensionDir, 'worker-prompt.md'), 'utf-8'),
+    readFile(join(extensionDir, 'rules.md'), 'utf-8')
+  ])
+
+  return template
+    .replaceAll('{{changeType}}', changeType)
+    .replaceAll('{{userContext}}', userContext || '(none)')
+    .replaceAll('{{rules}}', rules)
+}
+
+function waitForNextAgentEndAfterIdle(ctx: ExtensionCommandContext) {
+  return new Promise<unknown[]>((resolve) => {
+    agentEndWaiter = (messages) => {
+      void (async () => {
+        // `agent_end` also fires for transient provider failures that Pi may
+        // auto-retry. Wait until the whole agent run is idle, then use the
+        // latest worker messages captured by the global `agent_end` listener.
+        if (!ctx.isIdle()) {
+          await ctx.waitForIdle()
+        }
+        resolve(latestCommitWorkerMessages ?? messages)
+      })()
+    }
+  })
+}
+
+function getDisplayStatus(
+  content: string,
+  explicit?: CommitDisplayStatus
+): CommitDisplayStatus {
+  if (explicit) return explicit
+
+  const firstStatus = content.match(/^status:\s*(\S+)/im)?.[1]?.toLowerCase()
+  if (firstStatus === 'failed') return 'failed'
+  if (firstStatus === 'cancelled' || firstStatus === 'canceled') {
+    return 'cancelled'
+  }
+
+  return 'ok'
+}
+
+function formatWorkerErrorResult(error: string, partialSummary: string) {
+  const partial = partialSummary.trim()
+  return [
+    'status: failed',
+    `notes: Commit worker errored${partial ? ' after a partial response' : ' before producing a result'}.`,
+    `error: ${error}`,
+    partial ? `\nPartial response:\n${partial}` : ''
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+function formatCommitNotification(
+  summary: string,
+  status: CommitDisplayStatus
+): string {
+  const title =
+    status === 'failed'
+      ? 'Commit worker failed'
+      : status === 'cancelled'
+        ? 'Commit command cancelled'
+        : 'Commit worker finished'
+  const trimmedSummary = summary.trim()
+  return trimmedSummary ? `${title}:\n${trimmedSummary}` : title
+}
+
+function findLastCustomMessageIndex(messages: unknown[], customType: string) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index] as { customType?: string }
+    if (message.customType === customType) return index
+  }
+
+  return -1
+}
+
+function extractLastAssistantText(messages: unknown[], afterIndex = -1) {
+  const message = findLastAssistantMessage(messages, afterIndex)
+  return message ? extractTextFromContent(message.content).trim() : ''
+}
+
+function extractLastAssistantError(messages: unknown[], afterIndex = -1) {
+  const message = findLastAssistantMessage(messages, afterIndex)
+  if (message?.stopReason !== 'error') return undefined
+
+  return message.errorMessage?.trim() || 'Unknown provider error'
+}
+
+function findLastAssistantMessage(messages: unknown[], afterIndex = -1) {
+  for (let index = messages.length - 1; index > afterIndex; index--) {
+    const message = messages[index] as {
+      role?: string
+      content?: unknown
+      stopReason?: string
+      errorMessage?: string
+    }
+    if (message.role === 'assistant') return message
+  }
+
+  return undefined
+}
+
+function extractTextFromContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+
+  return content
+    .map((part) => {
+      if (
+        part &&
+        typeof part === 'object' &&
+        'type' in part &&
+        part.type === 'text' &&
+        'text' in part &&
+        typeof part.text === 'string'
+      ) {
+        return part.text
+      }
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}

package/extensions/changelog/rules.md

@@ -0,0 +1,107 @@
+# Changelog rules
+
+## Goal
+
+Changelogs should show that products are moving without turning every release into forced marketing.
+
+GitHub Releases are internal shipping records. Public changelog/social text is derived from PR changelog summaries and must stand alone because repositories may be private.
+
+## PR title prefixes
+
+Every PR title should start with exactly one prefix:
+
+- `feat:` new user-facing capability
+- `fix:` user-facing bug fix
+- `improve:` user-facing refinement, UX, performance, or reliability improvement
+- `internal:` infra, CI, tooling, refactor, tests, dependencies, logging, or other non-user-facing work
+
+These prefixes are release intent, not conventional commits.
+
+## Prefix rules
+
+- `feat:` means users can do something new.
+- `fix:` means a user-visible bug or broken behavior was corrected.
+- `improve:` means an existing user-facing workflow became clearer, faster, smoother, more reliable, or easier to use.
+- `internal:` means the work may matter to development/release/reliability but is not a public product change.
+
+Do not use `fix:` for technical-only fixes. Use `internal:` for TypeScript fixes, build fixes, CI fixes, test fixes, dependency fixes, refactor corrections, and internal error handling unless the corrected behavior is directly user-visible.
+
+## PR titles vs public summaries
+
+PR titles are classification and review metadata. They are not the public changelog source.
+
+Good PR titles are concrete:
+
+- `feat: add branded end cards for free exports`
+- `fix: prevent hidden tracks from rendering`
+- `improve: speed up waveform rendering for long projects`
+- `internal: centralize release deployment workflow`
+
+Avoid vague value-prop titles:
+
+- `feat: help users create better results`
+- `improve: improve editor experience`
+- `fix: make rendering better`
+
+## PR changelog section
+
+Every PR body should include:
+
+```md
+## Changelog
+
+Public summary:
+
+- ...
+
+Context:
+
+- ...
+```
+
+For `feat:`, `fix:`, and `improve:`, `Public summary` should contain one specific standalone user-facing sentence. Write it as if it may become one bullet in a public release post.
+
+For `internal:`, write exactly:
+
+```md
+Public summary:
+
+- None.
+```
+
+`Context` can include product/business details that help future release generation. It may be internal.
+
+## Public changelog source priority
+
+Release changelog generation should use sources in this order:
+
+1. PR body `## Changelog` → `Public summary`
+2. PR body `## Changelog` → `Context`
+3. GitHub Release body
+4. PR title, only for classification or fallback
+5. Commit messages, only as a last fallback
+
+If `Public summary` is `None`, skip that PR for public changelog output unless there is clear user-visible impact elsewhere in the release notes.
+
+## Public changelog output rules
+
+Public changelog/social text:
+
+- must not link to GitHub, PRs, commits, releases, or private repo artifacts
+- must not include PR numbers, commit hashes, or private URLs
+- should be standalone and understandable without release links
+- should use only meaningful user-facing changes
+- should make the product feel actively improved
+- should not force hype or flexing
+- should not include internal implementation details
+- should avoid generic phrases like `improved experience`, `seamless`, `empower`, and `game-changing`
+
+The same text should work for Discord and X.
+
+## GitHub Releases vs public changelog vs updates
+
+- GitHub Release: internal factual shipping record.
+- Public changelog/social post: short movement signal derived from public summaries.
+- Authored product update: bigger product story with screenshots/video/narrative when a release has enough substance.
+
+Not every release needs an authored product update.

package/extensions/changelog/worker-prompt.md

@@ -0,0 +1,127 @@
+You are the changelog commit worker.
+
+You are running in a temporary branch of the user's active Pi session. Use the provided change type and short user description as the primary source for commit/PR wording. Use git diff only to verify that the description matches the actual changes and to catch important omissions; do not try to rediscover or guess the change from the diff when a description is provided.
+
+Task:
+Commit current changes and create or update the GitHub PR.
+
+Command signature:
+/commit ${changeType} ${whatWasDoneShort}
+
+Selected change type:
+{{changeType}}
+
+What was done, in the user's words:
+{{userContext}}
+
+Before choosing commit messages, PR title, or PR changelog text, read and follow these rules exactly:
+
+{{rules}}
+
+Workflow:
+
+1. Inspect git status, current branch, diff, branch commits, candidate base branch, and existing PR.
+2. If a PR exists, read its current title, base branch, and full body before deciding what to change.
+3. If there are no changes to commit, update the PR body if useful, otherwise report no-op.
+4. If on main, create a branch.
+5. Commit current changes with a good prefixed commit message.
+6. Push the branch.
+7. If no PR exists for the branch, create one against the detected base branch.
+8. If PR exists, update title/body to reflect the full branch while preserving useful existing PR description content and existing base branch.
+9. When creating a PR body, always write the final markdown body to a file in a temporary directory and pass it to GitHub CLI with `--body-file`; do not pass markdown through `--body`.
+10. When updating an existing PR, avoid `gh pr edit`; it can fail on some repositories because GitHub CLI queries deprecated Projects Classic GraphQL fields. Use the REST API fallback described below instead.
+
+Rules:
+
+- Use the selected change type as user intent, unless it clearly contradicts the provided description and diff.
+- If selected type is `auto`, infer the type from the provided description first, then session context and diff, using the changelog rules.
+- Treat `whatWasDoneShort` as the user's rough wording. Convert awkward, terse, or informal language into clear PR title, commit message, and changelog wording according to the changelog rules.
+- Prefer the user's description over diff-derived wording. Use the diff to verify accuracy and specificity, not to invent a different story.
+- If the user's description is missing or too vague, use session context and diff as fallback.
+- `fix:` is only for user-visible bug fixes. Technical-only fixes must use `internal:`.
+- Commit message describes the current change using the user's description refined by the rules.
+- PR title describes the full branch using the user's description refined by the rules.
+- PR title must start with exactly one prefix from the changelog rules.
+- PR title is classification/review metadata, not the public changelog summary.
+- PR body `## Changelog` → `Public summary` is the canonical source for future public changelog generation.
+- Do not use vague value-prop titles.
+- Do not modify source files unless absolutely required to complete commit/PR metadata.
+- Do not run broad validation unless it is obviously cheap and relevant.
+
+PR base branch handling:
+
+- Never rely on `gh pr create`'s implicit base branch; it usually defaults to the repository default branch, which may be wrong for branches based on release, staging, or feature branches.
+- If an existing PR exists, preserve its current `baseRefName`. Do not change the PR base unless the user explicitly asked for that.
+- Before creating a new PR, determine the intended base branch and pass it explicitly with `--base "$base_branch"`.
+- Prefer a user-configured base if available, for example `git config --get branch.$current_branch.gh-merge-base` or `git config --get branch.$current_branch.noice-base`.
+- Otherwise fetch remote branches and infer the likely base from the branch ancestry. Compare candidate remote branches such as the repository default branch, `develop`, `staging`, `release/*`, and other long-lived branches, excluding the current head branch. Prefer the candidate with the most recent merge-base with `HEAD`; this usually recovers the branch the work was created from.
+- If the inferred base is not the repository default branch, mention that in the final notes. If the base is ambiguous, fail with a concise note asking the user to rerun with the intended base instead of opening a PR to the wrong branch.
+- Use this shape when creating a PR:
+
+```sh
+gh pr create --base "$base_branch" --title "$title" --body-file "$body_file"
+```
+
+PR body handling:
+
+- Always prepare the final PR body as a markdown file in a temporary directory, for example:
+  - `tmpdir=$(mktemp -d)`
+  - `body_file="$tmpdir/pr-body.md"`
+  - write the markdown body to `$body_file`
+- Create PRs with `gh pr create --title "..." --body-file "$body_file" ...`.
+- Update existing PRs with `gh api repos/OWNER/REPO/pulls/PR_NUMBER -X PATCH`; do not use `gh pr edit` for PR updates.
+- Do not use `--body` for markdown PR bodies; it can cause shell quoting and formatting problems.
+- For existing PR updates, use this safe REST flow and replace only the title/body values:
+
+```sh
+repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+pr_number=$(gh pr view --json number --jq .number)
+title='improve: concise PR title here'
+title_json=$(jq -Rn --arg value "$title" '$value')
+body_json=$(jq -Rs . < "$body_file")
+gh api "repos/$repo/pulls/$pr_number" \
+  -X PATCH \
+  --input <(printf '{"title":%s,"body":%s}' "$title_json" "$body_json") \
+  --jq '.html_url'
+```
+
+- If `gh api` succeeds, do not print the full JSON response; use `--jq` to return a concise confirmation such as `.html_url`.
+- If creating a new PR, use this body format:
+
+```md
+## Summary
+
+- ...
+
+## Changelog
+
+Public summary:
+
+- For feat/fix/improve: one specific standalone user-facing sentence.
+- For internal: None.
+
+Context:
+
+- Useful context for future release generation.
+
+## Verification
+
+- Commands run, or `Not run`.
+```
+
+- If updating an existing PR, enhance the existing body instead of blindly replacing it.
+- Preserve useful existing sections, reviewer notes, checklists, screenshots/videos, testing notes, linked issues, and any manually written context unless they are now inaccurate.
+- Ensure the final body still contains `## Summary`, `## Changelog`, and `## Verification`; add any missing sections in the standard format.
+- Refresh only the parts that need to reflect the full branch, especially `## Changelog` → `Public summary`, `Context`, and verification.
+- Remove or rewrite stale content only when the current diff/branch proves it is wrong.
+
+Final output:
+Return exactly five lines, with real values only:
+
+- Line 1 starts with `status:` followed by exactly one of these words: `committed`, `updated_pr`, `no_changes`, or `failed`.
+- Line 2 starts with `commit:` followed by the actual short SHA and commit message, or `none`.
+- Line 3 starts with `pr:` followed by the actual PR number, title, and URL, or `none`.
+- Line 4 starts with `verification:` followed by commands run, or `Not run`.
+- Line 5 starts with `notes:` followed by important caveats, or `none`.
+
+Do not include a fenced code block. Do not explain the format. Do not include the words `one of`, `actual`, `followed by`, or any placeholder text.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@noice-tech/pi-changelog",
+  "version": "1.0.0",
+  "description": "Pi changelog workflow for commits, pull requests, and public release notes.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "changelog",
+    "release-notes"
+  ],
+  "files": [
+    "extensions/**/*.ts",
+    "extensions/**/*.md",
+    "prompts/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noice-tech/noice-pi.git",
+    "directory": "packages/changelog"
+  },
+  "homepage": "https://github.com/noice-tech/noice-pi/tree/main/packages/changelog#readme",
+  "bugs": {
+    "url": "https://github.com/noice-tech/noice-pi/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-tui": "0.80.10",
+    "typescript": "6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/changelog/index.ts"
+    ],
+    "prompts": [
+      "./prompts/*.md"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --moduleResolution bundler --module ESNext --target ES2022 --skipLibCheck extensions/changelog/index.ts",
+    "test": "node ../../scripts/smoke-pack.mjs @noice-tech/pi-changelog packages/changelog"
+  }
+}

package/prompts/release-notes.md

@@ -0,0 +1,79 @@
+---
+description: generate public release notes/social copy from a GitHub release or release range
+argument-hint: '<version | from..to>'
+---
+
+Generate public release notes/social copy for the requested GitHub release or release range, and write public copy and private review sources to separate Markdown files.
+
+Input:
+`$ARGUMENTS`
+
+## Output files
+
+Derive `<slug>` from `$ARGUMENTS` by trimming surrounding whitespace, quotes, and backticks; keeping letters, numbers, dots, underscores, and hyphens; replacing every other character (including spaces and slashes) with `-`; collapsing repeated hyphens; and using `release-notes` if the result is empty.
+
+Create or overwrite both files:
+
+- public copy: `release-notes/<slug>.md`
+- private review sources: `.pi/tmp/pi-changelog/release-notes-sources/<slug>.md`
+
+Treat `.pi/tmp/` as ephemeral private workspace data that should remain ignored by Git and unpublished. Do not edit or create the consumer repository's `.gitignore`; only write the requested output files. Never put private source notes in the public artifact. After writing both files, reply only with both paths and a one-sentence summary of what was written.
+
+## Repository-specific style
+
+If `.pi/release-notes-style.md` exists, read it before writing public copy. It is the only canonical repository-specific style convention. It may refine audience, voice, terminology, formatting, examples, emoji use, and bullet style, but it must not override the classification, source-priority, or privacy rules below.
+
+## Shared changelog rules
+
+PR title prefixes are `feat:`, `fix:`, `improve:`, and `internal:`.
+
+- `feat:` means users can do something new.
+- `fix:` means a user-visible bug or broken behavior was corrected.
+- `improve:` means an existing user-facing workflow became clearer, faster, smoother, more reliable, or easier to use.
+- `internal:` means the work may matter to development, release, or reliability but is not a public product change.
+- Technical-only TypeScript, build, CI, test, dependency, refactor, and internal error-handling fixes are `internal:` unless corrected behavior is directly user-visible.
+- PR titles classify work; they are not the public changelog source.
+- PR body `## Changelog` → `Public summary` is the canonical public changelog atom.
+
+The input can be a single version/tag or a `from..to` range. Resolve bare and `v`-prefixed versions to Git tags. Use `gh` and `git` to inspect GitHub release bodies, tags, included merged PRs, and their titles and bodies.
+
+Use sources in this order:
+
+1. PR body `## Changelog` → `Public summary`
+2. PR body `## Changelog` → `Context`
+3. GitHub Release body
+4. PR title, only for classification or fallback
+5. Commit messages, only as a last fallback
+
+Include meaningful `feat:`, `fix:`, and `improve:` changes whose public summary is not `None`. Skip `internal:` changes and summaries of `None`. Be conservative with fixes.
+
+## Public copy
+
+The public file must contain no GitHub or release links, PR numbers, commit hashes, private URLs, private artifact references, internal source notes, or implementation details. It must stand alone.
+
+Follow `.pi/release-notes-style.md` when present. Otherwise write only a plain Markdown bullet list of specific public summaries, with no heading, intro, version line, emoji, CTA, links, or social framing.
+
+If there are no meaningful public changes, write exactly:
+
+```text
+No public changelog suggested for this release.
+```
+
+## Private review sources
+
+Write source review details only to `.pi/tmp/pi-changelog/release-notes-sources/<slug>.md` in this format:
+
+```md
+# Internal source notes
+
+Used:
+
+- <PR number/title or release source>
+
+Skipped:
+
+- <PR number/title and reason>
+
+Potential authored product update: yes/no
+Reason: <short reason>
+```

package/prompts/setup-release-notes-style.md

@@ -0,0 +1,77 @@
+---
+description: create or refine repo-specific release notes voice and formatting guidance
+argument-hint: '[product/audience/channel notes]'
+---
+
+Create or refine the repository's only canonical release notes style file:
+
+`.pi/release-notes-style.md`
+
+Input notes from the user:
+`$ARGUMENTS`
+
+Write concise guidance for humans and `/release-notes` that defines this product's public release notes audience, voice, terminology, and formatting.
+
+Do not duplicate package-owned rules about `feat`, `fix`, `improve`, or `internal` classification; inspecting GitHub releases, PRs, tags, commits, or ranges; source priority; internal source notes; privacy; or PR body structure.
+
+Process:
+
+1. Inspect the repository README and product documentation for audience, language, and public tone.
+2. If `.pi/release-notes-style.md` exists, refine it without replacing useful guidance.
+3. Create `.pi/` if needed.
+4. Write `.pi/release-notes-style.md`.
+5. Reply with the path and a concise summary.
+
+The style file should usually include:
+
+```md
+# Release notes style
+
+These instructions are for humans and for `/release-notes`.
+
+## Audience
+
+<who the public changelog is for>
+
+## Voice
+
+Use:
+
+- ...
+
+Avoid:
+
+- ...
+
+## Product language
+
+Use:
+
+- ...
+
+Avoid:
+
+- ...
+
+## Public format
+
+<exact public output format for this repo/channel>
+
+## Bullet style
+
+Bullets should be:
+
+- ...
+
+## Examples
+
+Good:
+
+- ...
+
+Bad:
+
+- ...
+```
+
+Keep it short and prefer concrete examples. If product-specific details cannot be inferred, use clear placeholders such as `<Product>` or ask a brief follow-up before writing.

package/prompts/unreleased.md

@@ -0,0 +1,101 @@
+---
+description: preview unreleased changelog candidates since the latest git tag
+argument-hint: ''
+---
+
+Preview what would go into a new release from merged PRs since the latest git tag. Do not create tags, releases, commits, branches, PRs, or files. Reply directly in chat only.
+
+Input:
+`$ARGUMENTS`
+
+Ignore arguments if provided. This command previews the current unreleased state only.
+
+Follow these shared changelog rules exactly:
+
+- PR title prefixes: `feat:`, `fix:`, `improve:`, and `internal:`.
+- `feat:` means users can do something new.
+- `fix:` means a user-visible bug or broken behavior was corrected.
+- `improve:` means an existing user-facing workflow became clearer, faster, smoother, more reliable, or easier to use.
+- `internal:` means the work may matter to development/release/reliability but is not a public product change.
+- Do not use technical-only fixes as public fixes. TypeScript, build, CI, test, dependency, refactor, and internal error-handling fixes are `internal:` unless the corrected behavior is directly user-visible.
+- PR titles are classification/review metadata. They are not the public changelog source.
+- PR body `## Changelog` → `Public summary` is the canonical public changelog atom.
+
+Workflow:
+
+1. Run `git fetch --tags`.
+2. Find the latest reachable tag with `git describe --tags --abbrev=0`.
+3. Get the latest tag commit date with `git log -1 --format=%cI <latest-tag>`.
+4. Inspect commits since the latest tag with `git log --oneline <latest-tag>..HEAD`.
+5. Use `gh` to find merged PRs after the latest tag commit date, normally with `gh pr list --state merged --search "merged:>=YYYY-MM-DD" --json number,title,url,mergedAt,body,mergeCommit,headRefName,baseRefName`.
+6. Cross-check the PRs against commits in `<latest-tag>..HEAD` when possible. If matching is uncertain, say so in the preview.
+7. For each relevant PR, read the title and body. Use `gh pr view` for full details if needed.
+8. Extract the PR body `## Changelog` section, especially:
+   - `Public summary:`
+   - `Context:`
+9. Classify each PR as:
+   - public candidate
+   - internal/skipped
+   - needs cleanup
+10. Reply directly with the preview. Do not write a file.
+
+Public candidate rules:
+
+- Include `feat:`, `fix:`, and `improve:` PRs when `Public summary` contains a meaningful user-facing summary.
+- Skip `internal:` PRs by default.
+- Skip PRs where `Public summary` is `None`.
+- Be conservative with `fix:`. Include only user-visible fixes, not technical/build/CI/test/refactor/dependency fixes.
+- Use `Public summary` text as the candidate release bullet when available.
+- If the PR appears user-facing but lacks a usable public summary, put it under `Needs cleanup`, not `Public candidates`.
+
+Needs cleanup rules:
+
+Flag PRs that may affect release quality, especially:
+
+- missing `## Changelog` section
+- missing `Public summary`
+- vague public summary such as “Improved experience” or “Bug fixes”
+- `feat:`, `fix:`, or `improve:` PR with `Public summary: None`
+- title prefix appears inconsistent with the changelog body
+- possible user-facing change only discoverable from title/commits, not from `Public summary`
+
+Output format:
+
+```md
+Unreleased preview since <latest-tag>
+
+Release recommendation: <yes|maybe|no>
+
+Public candidates: <count>
+Internal/skipped: <count>
+Needs cleanup: <count>
+
+## Public candidates
+
+- <public summary>
+  Source: #<number> <title>
+
+## Internal / skipped
+
+- #<number> <title>
+  Reason: <reason>
+
+## Needs cleanup
+
+- #<number> <title>
+  Issue: <issue>
+
+## Recommendation
+
+<short recommendation explaining whether this looks worth releasing now and what, if anything, should be cleaned up first.>
+
+## Notes
+
+- <include uncertainty about PR matching, no latest tag, no GitHub CLI access, or no unreleased commits only when relevant>
+```
+
+If there is no latest tag, say that an unreleased preview cannot be anchored to a previous release and summarize recent merged PRs only if safe.
+
+If there are no commits or PRs since the latest tag, recommend `no` and say there is nothing new to release.
+
+Keep the preview raw and factual. Do not generate polished public/social release notes. Do not include a title, CTA, or marketing framing beyond the required format.