copilot-session-usage 0.6.1__tar.gz → 0.6.2__tar.gz

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/.github/skills/gh-release-notes/SKILL.md

@@ -7,10 +7,10 @@ user-invocable: true
 
 # Release Notes Generator (Git Diff Based)
 
-Generate **end-user friendly** release notes by analyzing actual code changes between releases.
-No scripts required — uses git commands to understand what changed and why it matters.
+Generate **end-user-friendly, user-impact-only** release notes by analyzing the actual changes between releases.
+No scripts required — use git commands to understand what changed and why it matters to someone using the product.
 
-The output is meant to be **copy-pasted into a GitHub Release** (or similar).
+The output is meant to be **copy-pasted into a GitHub Release**. It must contain release-note sections only: never add a document title, preamble, file summary, commit summary, or closing separator.
 
 ---
 
@@ -33,12 +33,13 @@ What changed since the last release tag?
 ## What It Does
 
 1. **Reads actual diffs** — examines code changes, not just commit messages
-2. **Interprets for end-users** — no technical jargon, functions, or variable names
-3. **Categorizes intelligently** — Features, Enhancements, Bug Fixes, Breaking Changes
-4. **Adds concrete examples** — shows what users see or can do after the change
-5. **Links to public docs** — points to published documentation, not repo paths
-6. **Consolidates related changes** — groups related diffs, eliminates back-and-forth noise
-7. **Outputs clean markdown** — ready to paste into a GitHub Release note
+2. **Applies a user-impact gate** — includes a change only when a user-visible behavior, supported interface, user workflow, output, compatibility guarantee, or public documentation experience changed
+4. **Interprets for end-users** — no technical jargon, functions, variable names, file paths, or implementation summaries
+5. **Categorizes intelligently** — Features, Enhancements, Bug Fixes, Breaking Changes, or a no-product-impact classification
+6. **Adds concrete examples** — shows what users see or can do after a qualifying change
+7. **Links to public docs** — points to published documentation, not repo paths
+8. **Consolidates related changes** — groups related diffs and eliminates back-and-forth noise
+9. **Outputs clean markdown** — ready to paste into a GitHub Release note
 
 ---
 
@@ -58,19 +59,41 @@ Required:
 
 ## Analysis Process
 
+### Step 0: Apply the release-worthiness gate
+
+Before writing any bullet, ask: **What can a user do, observe, configure, rely on, or learn differently after this change?** Require evidence from the diff, public CLI/API help, supported configuration, user-facing output, migration behavior, or published documentation.
+
+Include a change only if it has at least one of these effects:
+
+- Adds, removes, fixes, or changes a user-facing feature, command, API, configuration option, output, error message, compatibility guarantee, or supported platform.
+- Changes runtime behavior in a way users can observe, such as performance, reliability, pricing data, security behavior, or data handling.
+- Changes public documentation that users actually consume to operate the product, including a new guide, changed instructions, or migration guidance.
+
+Do **not** infer user impact from a commit type, changed filename, test coverage, or the fact that a change is large. If the evidence does not show a user consequence, exclude it.
+
 ### Step 1: Collect Commits
 ```bash
 git log v1.0.0..v1.1.0 --oneline --no-merges
 ```
 Gather all commits in the specified range with their messages.
 
-### Step 2: Examine Diffs
+### Step 2: Examine relevant diffs
 ```bash
-git diff v1.0.0..v1.1.0 -- src/
+git diff v1.0.0..v1.1.0 -- . ':(exclude).github' ':(exclude)skills' ':(exclude)guidelines'
 ```
-Read actual code changes line-by-line to understand what changed.
+Read actual code changes line-by-line to understand behavior. Inspect excluded paths only when needed to verify whether they caused a direct user-visible consequence; never report the paths themselves.
 
-### Step 3: Interpret Changes
+Treat these as non-release content by default:
+
+- CI/CD workflows, automation, release jobs, repository settings, and bot configuration
+- Internal skills, agent prompts, contributor guidelines, engineering process, and maintainer runbooks
+- Tests, fixtures, formatting, linting, refactors, type annotations, and code organization
+- Dependency, lockfile, build, packaging, or development-environment changes without a user-visible runtime consequence
+- File counts, changed-file lists, commit counts, authors, implementation details, and internal URLs
+
+These exclusions can be overridden only when the diff proves a direct user impact, such as a packaging change that changes the installable artifact or a security fix that changes behavior for users.
+
+### Step 3: Interpret qualifying changes
 
 Translate technical changes into user impact:
 
@@ -85,6 +108,8 @@ Translate technical changes into user impact:
 
 **Key: Focus on the user's experience, not the code implementation.**
 
+Never turn a repository change into a release note merely by paraphrasing it. For example, “added CI workflow,” “updated contributor guidelines,” “improved project metadata,” and “7 files changed” are not release notes.
+
 ### Step 4: Identify Breaking Changes
 
 Breaking changes come from:
@@ -99,11 +124,17 @@ Breaking changes come from:
 
 ### Step 6: Categorize & Format
 
-Organize changes into buckets. **Only include sections that have content.** Omit empty sections entirely.
+Organize qualifying changes into buckets. **Only include sections that have content.** Omit empty sections entirely. Do not add a title heading.
 
-```markdown
-# Release Notes - v1.1.0
+If there are no qualifying product changes, use exactly one concise fallback section:
+
+- `## Maintenance` for a maintenance release containing internal upkeep, CI, release automation, dependency/build work, refactors, or other operational changes
+- `## Documentation` for a documentation-update release whose meaningful outcome is public user documentation, even when no runtime behavior changed
+- `## Internal` for an internal release containing changes intentionally limited to maintainers, contributors, or internal tooling
+
+Choose the most accurate fallback; do not list the underlying files or tasks. A maintenance release may say only that it contains maintenance updates. An internal release may say only that it contains internal updates. Do not manufacture examples or links for either.
 
+```markdown
 ## New Features
 - Added dark mode toggle in settings
 - New PDF export option
@@ -135,26 +166,25 @@ Organize changes into buckets. **Only include sections that have content.** Omit
 
 1. **Parse input** — extract `from_tag`, `to_tag`, `repo_path`, and optional filters
 2. **Discover public docs URL** — inspect `README.md`, `pyproject.toml`, `mkdocs.yml`, `docs/conf.py`, or `.readthedocs.yml` for the published documentation URL. Prefer ReadTheDocs, GitHub Pages, or the project's public docs site. If none is found, omit doc links.
-3. **Fetch commits** — run `git log` with range, collect hashes & messages
-4. **Read diffs per file** — `git show <hash>` for each commit, examine changed files
-5. **Interpret impact** — what does each change mean to users?
-6. **Detect breaking changes** — scan for BREAKING markers, API removals, schema changes
-7. **Group by category** — assign each change to **New Features**, **Enhancements**, **Bug Fixes**, **Breaking Changes**, **Examples**, or **Documentation**
-8. **Build examples** — for each user-facing change, look at README, docs, tests, or CLI help in the diff and add a short "what the user gets" example when it clarifies the change
-9. **Consolidate** — merge related items, remove duplicates and flip-flops
-10. **Format markdown** — generate clean bullet points with proper headings
-11. **Omit empty sections** — do not print a section if it has no bullets
-12. **Use public docs links** — every Documentation bullet and every feature/enhancement docs reference must use the public URL with a fragment identifier, not a repo-relative path
+3. **Fetch commits** — run `git log` with range, collect hashes and messages
+4. **Read diffs per file** — use `git show <hash>` for each relevant commit and examine changed behavior, not just filenames
+5. **Apply the user-impact gate** — discard CI, internal, process, and implementation-only changes unless the diff proves direct user impact
+6. **Interpret impact** — state what users can do, observe, configure, rely on, or learn differently
+7. **Detect breaking changes** — scan for BREAKING markers, public API removals, format changes, migrations, and changed defaults
+8. **Group by category** — assign each qualifying change to **New Features**, **Enhancements**, **Bug Fixes**, **Breaking Changes**, **Examples**, or **Documentation**
+9. **Build examples** — for each user-facing change, use README, public docs, tests, or CLI help as evidence and add a short example only when it clarifies the user outcome
+10. **Consolidate** — merge related items, remove duplicates and flip-flops
+11. **Use a fallback** — if no product change qualifies, emit exactly one of **Maintenance**, **Documentation**, or **Internal**
+12. **Format markdown** — generate clean section headings and bullets with no title, preamble, footer, file summary, or commit summary
+13. **Use public docs links** — every Documentation bullet and every feature/enhancement docs reference must use the public URL with a fragment identifier, not a repo-relative path
 
 ---
 
 ## Output Format
 
-**Clean markdown** for a GitHub Release:
+**Clean markdown** for a GitHub Release body:
 
 ```markdown
-# Release Notes - v1.1.0
-
 ## New Features
 - Added dark mode toggle in settings
 - New PDF export option
@@ -179,16 +209,26 @@ Organize changes into buckets. **Only include sections that have content.** Omit
 - [Upgrade instructions](https://docs.example.com/upgrade#database)
 ```
 
+For a release with no runtime product impact, use a short note such as:
+
+```markdown
+## Maintenance
+- Maintenance release with no user-facing behavior changes.
+```
+
 **Key Rules:**
 - One line per bullet point
 - No sub-bullets or elaborate descriptions
-- User impact only (not implementation details)
+- User impact only (not implementation details, changed-file summaries, CI, internal process, or contributor guidance)
+- Do not include a title heading; the GitHub Release supplies the title
 - Use public documentation URLs; never use repo-relative paths like `docs/...` or `README.md`
 - Use fragment identifiers (`#section-name`) to point to specific docs sections
 - Add an **Examples** section when the diff shows a CLI command, API call, config snippet, or before/after behavior
-- Add a **Documentation** section when docs were added or updated, linking to the published page
+- Add a **Documentation** section only when public user documentation changed in a way users need or benefit from; never report internal guidelines or maintainer documentation
 - Multiple links OK if they point to different topics
 - Omit any section that has no bullets
+- If no user-facing change qualifies, emit exactly one concise `Maintenance`, `Documentation`, or `Internal` section
+- Never include file counts, changed-file lists, commit metadata, CI/workflow summaries, or a closing separator
 - Do not add a "Notes", "Miscellaneous", or "Other" catch-all section
 
 ---
@@ -199,7 +239,7 @@ When this skill is invoked by a CI job with an explicit request for machine-read
 
 - Honor the requested tag range and repository path exactly.
 - Do not modify, commit, or push repository files unless the caller explicitly requests it.
-- Return only the final release-note Markdown, without an explanation or a code fence.
+- Return only the final release-note Markdown, without an explanation, title heading, or code fence.
 - Preserve the user-impact categories, examples, breaking-change detection, and public documentation links described above.
 
 ## How to Use This Skill in a Session
@@ -226,6 +266,7 @@ Generate release notes from v2.1.0 to v2.2.0 for /path/to/my-app
 ✅ **Do:**
 - Read actual diffs to understand changes
 - Use end-user language ("improved performance" not "optimized O(n) loop")
+- Require evidence of a user-visible consequence before including a change
 - Include breaking changes prominently
 - Group related changes
 - Add concrete examples drawn from README, docs, tests, or CLI help in the diff
@@ -239,6 +280,8 @@ Generate release notes from v2.1.0 to v2.2.0 for /path/to/my-app
 - Include dependency bumps or build changes unless they are user-visible
 - Include secrets, passwords, or internal URLs
 - Use repo-relative paths like `docs/source/how-to/...` or `README.md`
+- Report CI, workflows, internal skills, contributor guidelines, maintainer process, file counts, or changed-file lists as release content
+- Add a title heading to the generated body
 - Make up changes not shown in diffs
 
 ---
@@ -264,8 +307,8 @@ Generate release notes from v2.1.0 to v2.2.0 for /path/to/my-app
 
 ## Limitations
 
-- Requires git repository with proper tags
+- Requires a git repository with proper tags
 - Complex changes may need human interpretation
-- Very large diffs (1000+ files) summarized by file count
+- Very large diffs should be reduced to their evidenced user impact; never summarize them by file count
 - Works best with semantic versioning (v1.0.0 format)
-- Needs meaningful commit messages for best results
+- Needs meaningful commit messages for best results, but commit messages alone are never evidence of user impact

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/.github/workflows/release-notes.yml

@@ -80,7 +80,7 @@ jobs:
 
           Generate the final release notes for ${TARGET_TAG}, covering the actual changes from ${PREVIOUS_TAG} to ${TARGET_TAG} in ${GITHUB_WORKSPACE}.
 
-          Follow the skill's diff-based analysis process. Use the project's public documentation URL when documentation links are appropriate. Return only the final release-note Markdown, with no introduction, explanation, or code fence. Do not modify any repository files."
+          Follow the skill's diff-based analysis process. Include only changes with a proven user-facing consequence; exclude CI, workflows, release automation, internal skills, guidelines, tests, file lists, and other repository housekeeping unless the diff proves direct product impact. If there is no product impact, emit one concise Maintenance, Documentation, or Internal section. Return only the final release-note Markdown, with no title heading, introduction, explanation, file summary, or code fence. Do not modify any repository files."
 
           gh copilot -- \
             --prompt "$prompt" \

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/.github/workflows/release.yml

@@ -143,7 +143,7 @@ jobs:
 
           Generate the final release notes for ${TARGET_TAG}, covering the actual changes from ${PREVIOUS_TAG} to ${TARGET_TAG} in ${GITHUB_WORKSPACE}.
 
-          Follow the skill's diff-based analysis process. Use the project's public documentation URL when documentation links are appropriate. Return only the final release-note Markdown, with no introduction, explanation, or code fence. Do not modify, commit, or push any repository files."
+          Follow the skill's diff-based analysis process. Include only changes with a proven user-facing consequence; exclude CI, workflows, release automation, internal skills, guidelines, tests, file lists, and other repository housekeeping unless the diff proves direct product impact. If there is no product impact, emit one concise Maintenance, Documentation, or Internal section. Return only the final release-note Markdown, with no title heading, introduction, explanation, file summary, or code fence. Do not modify, commit, or push any repository files."
 
           gh copilot -- \
             --prompt "$prompt" \

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/AGENTS.md

@@ -77,6 +77,16 @@ to understand the rules of the knowledge base in `knowledge/`.
 - **Detail levels**: `minimal` < `compact` < `full`
 - **Output formats**: `json`, `table`, `detailed` (alias for table + full detail)
 
+## Git History and Pull Requests
+
+This repository must maintain a linear history. **Never create a merge commit.**
+
+- Rebase a feature branch onto the current target branch before opening or updating a pull request: `git fetch origin main && git rebase origin/main`.
+- When the target branch advances, rebase again; do not merge `main` into the feature branch.
+- Resolve conflicts during the rebase, run the relevant checks, and update the remote branch with `git push --force-with-lease` when required.
+- Merge pull requests only with a squash merge or a rebase/fast-forward merge. Never use a merge commit or `--no-ff`.
+- Do not force-push protected branches; `--force-with-lease` is permitted only for the contributor's feature branch.
+
 ## Before You Commit
 
 ```bash

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copilot-session-usage
-Version: 0.6.1
+Version: 0.6.2
 Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
 Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
 Project-URL: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/

copilot_session_usage-0.6.2/knowledge/findings/2026.07.13-14.27-release-notes-overreported-maintainer-changes.md

@@ -0,0 +1,34 @@
+---
+type: Finding
+title: Release-note generation reported maintainer changes as user-facing
+  features
+description: The generated v0.6.1 draft release notes described contributor
+  guidelines, project metadata, and file counts instead of observable product
+  changes.
+tags: [release-notes, copilot, user-impact, github-actions]
+timestamp: 2026-07-13T14:27:04Z
+confidence: high
+context: >-
+  Observed in the draft release generated for v0.6.1 from the v0.6.0 range in
+  gsemet/copilot-session-usage. The custom release-note skill and workflow did
+  not explicitly exclude internal guidelines, CI/process changes, or file
+  summaries, and the generated body included those items plus a title heading.
+  The comparison was made against the user-facing v0.5.0 release notes.
+links: []
+backlinks: []
+---
+
+The v0.6.1 release-note generation treated repository-maintenance changes as
+product features: it listed knowledge-base and commit-message guidelines,
+contributing documentation, project metadata, and counts of modified/added
+files. These items were not shown as changes that users could observe or use.
+
+This matters because a diff-based release-note prompt needs an explicit
+user-impact gate and a hard exclusion for CI, internal process, contributor
+material, and implementation-only changes. A no-product-impact release should
+instead receive one concise internal, documentation-update, or maintenance
+classification, and the generated body should not add its own title heading.
+
+Caveat: this finding is based on one generated draft release and the local
+skill/workflow revision made afterward; it does not establish that every
+release range will produce the same pollution.

{copilot_session_usage-0.6.1 → copilot_session_usage-0.6.2}/knowledge/findings/index.md

@@ -6,5 +6,6 @@ The body and claim are immutable once written. To correct a Finding, write a new
 Belongs to the Storage layer. Findings are promoted into Concepts or Structures when they converge and stabilize. They may also support Principles.
 
 - [cache_write approximated via fresh_input — matches AIC panel exactly](2026.07.02-23.00-cache-write-approximation.md) — VS Code JSONL logs and agent-traces.db both lack cache_creation token counts. Approximating cache_creation as fresh_input = inputTokens - cachedTokens and billing only the incremental delta (cache_write - input) / 1M produces an exact match to the VS Code AIC panel. Implemented in estimate_cost since v0.3.  [Finding]
+- [Release-note generation reported maintainer changes as user-facing features](2026.07.13-14.27-release-notes-overreported-maintainer-changes.md) — The generated v0.6.1 draft release notes described contributor guidelines, project metadata, and file counts instead of observable product changes.  [Finding]
 - [Subagent Logs Use runSubagent Prefix](2026.07.02-00.00-subagent-logs-runsubagent-prefix.md) — Subagent activity is recorded in separate JSONL files prefixed with "runSubagent-" inside the session debug-logs directory.  [Finding]
 - [title-*.jsonl adds 1 LLM call and its tokens to tool totals; VS Code panel excludes it](2026.07.02-22.00-title-generation-not-counted-as-model-turn.md) — The VS Code Agent Debug panel "Model Turns" counter excludes title-generation calls. copilot-session-usage counts them. The delta is exactly the title-*.jsonl file's token counts.  [Finding]