@noice-tech/pi-changelog 1.0.0 → 1.0.3

package/README.md

@@ -32,7 +32,31 @@ Pi packages run with the permissions granted to Pi. **Only use this package when
 
 `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`.
+`/commit` runs its worker on a side branch of the current session at low thinking, then restores your previous thinking level when it finishes. If you invoke it during an active agent turn, the change-type selector opens immediately; after your selection, the command waits for that turn to settle before starting the worker.
+
+### PR title package scopes
+
+Commit messages always keep the unscoped form:
+
+```text
+internal: update PR title generation
+```
+
+PR titles stay unscoped in single-package repositories and workspaces. In a multi-package workspace, the title identifies one primary package by its workspace directory basename:
+
+```text
+internal(changelog): update PR title generation
+```
+
+The worker determines the primary package from the PR's intent and full branch against its base. Incidental shared files such as a lockfile do not override a clear primary package. Root-only, cross-cutting, or ambiguous multi-package changes use `monorepo`:
+
+```text
+internal(monorepo): centralize release tooling
+```
+
+Both scoped and unscoped PR titles are valid changelog inputs. Package scopes are metadata and are not included in public changelog copy.
+
+The canonical shared classification and package-scope rules live in `extensions/changelog/rules.md`.
 
 ## Repository-specific release-note style
 

package/extensions/changelog/index.ts

@@ -30,7 +30,7 @@ const CHANGE_TYPE_OPTIONS: Array<{ type: ChangeType; label: string }> = [
 
 const MESSAGE_TYPE = 'noice-changelog-commit-result'
 const PROMPT_MESSAGE_TYPE = 'noice-changelog-commit-worker-prompt'
-const STATUS_KEY = 'noice-changelog'
+const COMMIT_WORKER_WIDGET_KEY = 'noice-changelog-commit-worker'
 
 type CommitDisplayStatus = 'ok' | 'cancelled' | 'failed'
 
@@ -41,6 +41,7 @@ interface CommitResultDetails {
   status?: CommitDisplayStatus
 }
 
+let commitCommandPending = false
 let commitWorkerRunning = false
 let agentEndWaiter: ((messages: unknown[]) => void) | undefined
 let latestCommitWorkerMessages: unknown[] | undefined
@@ -154,26 +155,40 @@ export default function noiceChangelogExtension(pi: ExtensionAPI) {
       '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')
+      if (commitCommandPending || commitWorkerRunning) {
+        ctx.ui.notify('Commit command is already active', 'warning')
         return
       }
 
-      await ctx.waitForIdle()
+      commitCommandPending = true
+      let prepared: Awaited<ReturnType<typeof prepareCommit>>
+      try {
+        prepared = await prepareCommit(args, ctx)
+      } catch (error) {
+        commitCommandPending = false
+        throw error
+      }
 
-      const parsed = await resolveChangeTypeAndContext(args, ctx)
-      if (!parsed) {
+      if (!prepared) {
+        commitCommandPending = false
         return
       }
 
+      const { parsed, prompt } = prepared
       const startLeafId = ctx.sessionManager.getLeafId()
-      const prompt = await buildWorkerPrompt(parsed.changeType, parsed.context)
+      const previousThinkingLevel = pi.getThinkingLevel()
 
+      // Establish the running guard before releasing the pending guard. Keeping
+      // this transition synchronous prevents a re-entrant command from starting
+      // a second worker and overwriting the singleton agent-end waiter.
       commitWorkerRunning = true
-      ctx.ui.setStatus(STATUS_KEY, 'running in session branch...')
-      ctx.ui.notify(`Starting commit worker (${parsed.changeType})`, 'info')
+      commitCommandPending = false
 
       try {
+        showCommitWorkerBanner(ctx)
+        ctx.ui.notify(`Starting commit worker (${parsed.changeType})`, 'info')
+        pi.setThinkingLevel('low')
+
         const agentEnd = waitForNextAgentEndAfterIdle(ctx)
         latestCommitWorkerMessages = undefined
         pi.sendMessage(
@@ -302,7 +317,8 @@ export default function noiceChangelogExtension(pi: ExtensionAPI) {
         })
         ctx.ui.notify(`Commit worker failed:\n${message}`, 'error')
       } finally {
-        ctx.ui.setStatus(STATUS_KEY, undefined)
+        pi.setThinkingLevel(previousThinkingLevel)
+        ctx.ui.setWidget(COMMIT_WORKER_WIDGET_KEY, undefined)
         commitWorkerRunning = false
         latestCommitWorkerMessages = undefined
       }
@@ -310,6 +326,20 @@ export default function noiceChangelogExtension(pi: ExtensionAPI) {
   })
 }
 
+function showCommitWorkerBanner(ctx: ExtensionCommandContext) {
+  const message = 'Commit worker running on a side branch of this session…'
+
+  if (ctx.mode !== 'tui') {
+    ctx.ui.setWidget(COMMIT_WORKER_WIDGET_KEY, [message])
+    return
+  }
+
+  ctx.ui.setWidget(
+    COMMIT_WORKER_WIDGET_KEY,
+    (_tui, theme) => new Text(theme.fg('warning', message), 1, 0)
+  )
+}
+
 function getCommitArgumentCompletions(prefix: string) {
   const trimmedStart = prefix.trimStart()
   const leadingWhitespace = prefix.slice(0, prefix.length - trimmedStart.length)
@@ -341,6 +371,29 @@ function getCommitArgumentCompletions(prefix: string) {
   ]
 }
 
+async function prepareCommit(
+  args: string | undefined,
+  ctx: ExtensionCommandContext
+) {
+  const parsed = await resolveChangeTypeAndContext(args, ctx)
+  if (!parsed) return null
+
+  if (!ctx.isIdle()) {
+    ctx.ui.notify(
+      'Commit queued; waiting for the current agent turn to finish',
+      'info'
+    )
+  }
+
+  await ctx.waitForIdle()
+  const prompt = await buildWorkerPrompt(parsed.changeType, parsed.context)
+  // Prompt loading is asynchronous. Re-check idle so another user turn cannot
+  // slip in between the original wait and worker startup.
+  await ctx.waitForIdle()
+
+  return { parsed, prompt }
+}
+
 async function resolveChangeTypeAndContext(
   args: string | undefined,
   ctx: ExtensionCommandContext

package/extensions/changelog/rules.md

@@ -6,42 +6,74 @@ Changelogs should show that products are moving without turning every release in
 
 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
+## PR title format
 
-Every PR title should start with exactly one prefix:
+Every PR title should start with exactly one change type. The title format depends on the repository's package layout:
 
-- `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
+- Single-package repository or workspace: `type: description`
+- Multi-package workspace: `type(package): description`
 
-These prefixes are release intent, not conventional commits.
+The supported change types are:
 
-## Prefix rules
+- `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
 
-- `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.
+These types express release intent. They are not Conventional Commits.
 
-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.
+## Package scope rules
 
-## PR titles vs public summaries
+- First inspect the repository's workspace configuration and package roots. Count distinct package roots declared by the workspace configuration or its ecosystem equivalent. If there is no formal workspace configuration, count independently built or published package roots identified by the repository's manifests.
+- A private root manifest used only to coordinate workspace tooling does not count as a package. A root that is itself an independently built or published package does count.
+- If the repository contains zero or one package root, omit the scope. If it contains two or more, treat it as a multi-package workspace.
+- In a multi-package workspace, use the primary package's workspace directory basename as the scope. For example, work primarily in `packages/renderer` uses `renderer` even if its manifest name is `@example/pi-renderer`.
+- Determine the primary package from the PR's intent and the full branch diff against the detected PR base. Resolve the title from the resulting branch after the current change is committed, not from only the previous branch state, current worktree, or latest commit.
+- Incidental shared-file changes, such as a root lockfile updated alongside one package, do not override a clear primary package.
+- When multi-package work is root-only, cross-cutting, or has no clear primary package, use `monorepo`.
+- Use exactly one scope. Do not list several package names.
 
-PR titles are classification and review metadata. They are not the public changelog source.
+Examples:
 
-Good PR titles are concrete:
+- Single-package repository: `feat: add branded end cards for free exports`
+- Primary package: `fix(renderer): prevent hidden tracks from rendering`
+- Cross-cutting multi-package work: `internal(monorepo): centralize release deployment workflow`
+
+## Commit message format
+
+Commit messages always remain unscoped, regardless of repository layout:
 
 - `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`
 
+Do not add package scopes to commit messages and do not rewrite existing commits merely to match a PR title.
+
+## Change type 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, package, and review metadata. They are not the public changelog source.
+
+Good PR titles are concrete:
+
+- `feat: add branded end cards for free exports`
+- `fix(renderer): prevent hidden tracks from rendering`
+- `improve(editor): speed up waveform rendering for long projects`
+- `internal(monorepo): centralize release deployment workflow`
+
 Avoid vague value-prop titles:
 
 - `feat: help users create better results`
-- `improve: improve editor experience`
-- `fix: make rendering better`
+- `improve(editor): improve editor experience`
+- `fix(renderer): make rendering better`
 
 ## PR changelog section
 
@@ -59,9 +91,9 @@ 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 `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:
+For `internal`, write exactly:
 
 ```md
 Public summary:
@@ -83,6 +115,8 @@ Release changelog generation should use sources in this order:
 
 If `Public summary` is `None`, skip that PR for public changelog output unless there is clear user-visible impact elsewhere in the release notes.
 
+Package scopes in PR titles are metadata only. Do not copy them into public changelog text; use the canonical public summary instead.
+
 ## Public changelog output rules
 
 Public changelog/social text:

package/extensions/changelog/worker-prompt.md

@@ -1,6 +1,6 @@
 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.
+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 the current commit wording and for PR changelog text about the current change. Use the current diff only to verify that description and catch important omissions; do not try to rediscover or guess the current change from the diff when a description is provided. Resolve the PR title separately from the cumulative full branch as described below.
 
 Task:
 Commit current changes and create or update the GitHub PR.
@@ -20,29 +20,35 @@ Before choosing commit messages, PR title, or PR changelog text, read and follow
 
 Workflow:
 
-1. Inspect git status, current branch, diff, branch commits, candidate base branch, and existing PR.
+1. Inspect git status, current branch, staged and unstaged changes, branch commits, candidate base branch, existing PR, and repository workspace/package layout.
 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.
+3. Determine whether there are changes to commit or useful PR metadata updates to make. If there are neither, report no-op.
+4. If there are changes to commit and the current branch is main, create a branch.
+5. If there are changes to commit, commit them with a good unscoped prefixed commit message.
+6. Resolve the PR title format and, for a multi-package workspace, its one primary package from the PR's cumulative intent and the resulting full branch diff against the detected or preserved PR base. Resolve this after committing the current changes so the diff includes them; do not use only the latest commit.
+7. Push the branch if needed.
+8. If no PR exists for the branch, create one against the detected base branch.
+9. If a PR exists, update its title/body to reflect the full branch while preserving useful existing PR description content and its existing base branch.
+10. 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`.
+11. 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.
+- Use the selected change type as user intent for the current commit, unless it clearly contradicts the provided description and diff.
+- If selected type is `auto`, infer the current commit's type from the provided description first, then session context and diff, using the changelog rules.
+- Treat `whatWasDoneShort` as the user's rough wording for the current change. Convert awkward, terse, or informal language into a clear commit message and changelog wording according to the changelog rules.
+- Prefer the user's description over diff-derived wording for the current commit. Use the current diff to verify accuracy and specificity, not to invent a different story.
+- The PR title must describe the cumulative full branch. Use the user's description for it only when that description represents the full branch; otherwise use the existing PR title/body, branch commits, session context, and full branch diff to preserve the established branch intent. Do not let the latest delta replace a broader PR purpose.
+- If the user's description is missing or too vague for the current change, use session context and the current diff as fallback.
+- `fix` is only for user-visible bug fixes. Technical-only fixes must use `internal`.
+- Commit messages always use the unscoped `type: description` format, including in multi-package workspaces. Do not add a package scope to a commit message or rewrite existing commits to match the PR title.
+- Derive the PR title from the cumulative full-branch sources described above, not by defaulting to the latest current-change description.
+- In a single-package repository or workspace, the PR title uses `type: description`.
+- In a multi-package workspace, the PR title uses `type(package): description`, where `package` is the primary package's workspace directory basename.
+- For root-only or cross-cutting work in a multi-package workspace, or when no one package is clearly primary, use `type(monorepo): description`.
+- Incidental shared files such as a root lockfile do not override a clear primary package. Use exactly one package scope rather than listing every affected package.
+- When updating an existing PR, preserve its package scope only if it still matches the repository layout and full branch; otherwise correct the title.
+- PR title type and package scope are 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.
@@ -76,7 +82,7 @@ PR body handling:
 ```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="$resolved_pr_title"
 title_json=$(jq -Rn --arg value "$title" '$value')
 body_json=$(jq -Rs . < "$body_file")
 gh api "repos/$repo/pulls/$pr_number" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noice-tech/pi-changelog",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Pi changelog workflow for commits, pull requests, and public release notes.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,6 @@
   },
   "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"
+    "test": "node --test test/*.test.mjs && node ../../scripts/smoke-pack.mjs @noice-tech/pi-changelog packages/changelog"
   }
 }

package/prompts/release-notes.md

@@ -25,13 +25,14 @@ If `.pi/release-notes-style.md` exists, read it before writing public copy. It i
 
 ## 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.
+Valid PR titles use either unscoped `type: description` or package-scoped `type(package): description` form. The change types 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.
+- A package scope, including `monorepo`, is metadata. It does not change the change type and must not be copied into public changelog text.
 - PR titles classify work; they are not the public changelog source.
 - PR body `## Changelog` → `Public summary` is the canonical public changelog atom.
 
@@ -45,7 +46,7 @@ Use sources in this order:
 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.
+Include meaningful `feat`, `fix`, and `improve` changes, whether scoped or unscoped, whose public summary is not `None`. Skip `internal` changes and summaries of `None`. Be conservative with fixes.
 
 ## Public copy
 

package/prompts/unreleased.md

@@ -12,12 +12,14 @@ Ignore arguments if provided. This command previews the current unreleased state
 
 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.
+- Valid PR titles use either unscoped `type: description` or package-scoped `type(package): description` form.
+- The change types 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/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.
+- A package scope, including `monorepo`, is metadata. It does not change the change type and must not be copied into public changelog text.
 - PR titles are classification/review metadata. They are not the public changelog source.
 - PR body `## Changelog` → `Public summary` is the canonical public changelog atom.
 
@@ -41,10 +43,10 @@ Workflow:
 
 Public candidate rules:
 
-- Include `feat:`, `fix:`, and `improve:` PRs when `Public summary` contains a meaningful user-facing summary.
-- Skip `internal:` PRs by default.
+- Include `feat`, `fix`, and `improve` PRs, whether scoped or unscoped, when `Public summary` contains a meaningful user-facing summary.
+- Skip `internal` PRs by default, whether scoped or unscoped.
 - Skip PRs where `Public summary` is `None`.
-- Be conservative with `fix:`. Include only user-visible fixes, not technical/build/CI/test/refactor/dependency fixes.
+- 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`.
 
@@ -55,8 +57,8 @@ 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
+- `feat`, `fix`, or `improve` PR, whether scoped or unscoped, with `Public summary: None`
+- title change type appears inconsistent with the changelog body
 - possible user-facing change only discoverable from title/commits, not from `Public summary`
 
 Output format: