@eldrforge/kodrdriv 1.2.13 → 1.2.16

package/dist/prompt/instructions/commit.md

@@ -1,13 +1,27 @@
 **🔧 Task Definition**
 
-You are generating a Git commit message based on the content provided below. The content contains several critical sections:
+You are generating a Git commit message that describes **ONLY THE CURRENT DIFF**.
 
-* **\[User Direction]** — When present, this is the PRIMARY guidance for your commit message focus. This describes the motivation, goals, or intent behind the change from the user's perspective. This should be the starting point and main theme of your commit message.
-* **\[User Context]** — When present, this provides IMPORTANT additional context about the user's situation, environment, or background that should inform your commit message understanding and approach.
-* **\[Diff]** — A code diff representing the actual modifications. Analyze this to understand *what* was changed. **THIS IS THE CURRENT CHANGE YOU ARE DESCRIBING** — focus your commit message on explaining these specific modifications.
-* **\[Project Files]** — When no diff is available (e.g., in a new repository), this section contains the current project files. Analyze these to understand the project structure and generate an appropriate initial commit message that describes what was added to the repository.
-* **\[Recent GitHub Issues]** — When present, this contains recently closed GitHub issues, with priority given to issues from milestones matching the current version. **Use this context to understand WHY changes might have been made and to identify which specific issues or features the current changes address.** This helps you provide motivation and context for the changes, especially for large commits that may address multiple issues.
-* **\[Log Context]** — A short history of recent commit messages. **IMPORTANT: This is provided ONLY for background context and temporal continuity. DO NOT use this to drive your commit message focus or content. DO NOT describe previous commits or reference past changes. Your commit message should describe ONLY the current diff/change.**
+---
+
+## ⚠️ CRITICAL RULES - READ FIRST
+
+1. **THE DIFF IS YOUR ONLY SOURCE OF TRUTH** - Your commit message must describe ONLY what appears in the `[Diff]` section
+2. **IGNORE LOG CONTEXT** - Previous commits are shown for background only. DO NOT describe them, reference them, or let them influence your message
+3. **CITE SPECIFIC FILES** - Every change you mention must reference actual files from the diff (e.g., "Remove post-publish sync logic in src/commands/publish.ts")
+4. **NO HALLUCINATIONS** - If you mention a change, it MUST exist in the diff. Describing changes not in the diff is a critical failure
+5. **LENGTH FOLLOWS SCOPE** - Typical commits are 3-6 lines. Very large architectural changes may warrant essay-length messages, but every line must still describe actual changes from the diff
+
+---
+
+## 📋 Input Sections
+
+* **\[User Direction]** — When present, use this to understand the user's INTENT, but your commit message must still accurately describe what's in the diff
+* **\[User Context]** — Optional background about the user's environment
+* **\[Diff]** — **THE ONLY SOURCE OF TRUTH** - This shows exactly what changed. Describe ONLY these changes
+* **\[Project Files]** — Only present for new repositories with no diff
+* **\[Recent GitHub Issues]** — Optional context for understanding motivation. Only reference issues if the diff clearly addresses them
+* **\[Log Context]** — **IGNORE THIS** - Previous commit messages shown for background only. DO NOT describe previous commits or copy their language
 
 ---
 
@@ -15,100 +29,105 @@ You are generating a Git commit message based on the content provided below. The
 
 ### ✅ DO:
 
-* **PRIORITIZE User Direction**: If `[User Direction]` is provided, make it the central theme and starting point of your commit message. Let it guide the narrative and focus.
-* **CONSIDER User Context**: If `[User Context]` is provided, use it to inform your understanding and tailor your commit message appropriately to the user's situation.
-* **LEVERAGE GitHub Issues for Context**: If `[Recent GitHub Issues]` is provided, use it to:
-  - Understand the **motivation** behind changes (why they were made)
-  - Identify **specific issues** the changes address (e.g., "Fixes #123: authentication timeout")
-  - Provide better context for **large commits** that may touch multiple areas
-  - Connect **related changes** to their original requirements or bug reports
-  - **For smaller commits**: Only reference issues if directly relevant; don't force connections
-  - **For larger commits**: Use issues to explain the broader context and group related changes
-* **FOCUS ON THE CURRENT CHANGE**: Your commit message should describe only what is happening in the current diff or project files — not previous work or future plans. For new repositories with project files, focus on describing what has been initially added.
-* Start with a **clear, concise summary** of what was changed and why — grounded in the `User Direction` when present and informed by any `User Context`.
-* **ALWAYS GROUP CHANGES INTO SEPARATE LINES**: Break down changes into distinct logical groups, with each group on its own line. Even for simple changes, use multiple lines when there are different types of modifications.
-* **USE BULLET POINTS BY DEFAULT**: Format most commit messages with bullet points to clearly separate different groups of changes.
-* **Refer to specific changes** seen in the `Diff` or specific files/components in `Project Files`, and explain why those changes matter when it's non-obvious.
-* Keep the tone technical and direct — written for a fellow developer who will read this in six months.
+* **Ground every statement in the diff** - Mention specific files that changed (e.g., "Add retry logic to src/api/client.ts")
+* **Start with clear intent** - One line explaining the overall purpose
+* **Use bullet points** - Separate distinct changes into individual bullets
+* **Be specific** - "Remove 68 lines of post-publish sync code" not "Refactor publish flow"
+* **Match length to scope** - Most commits are 3-6 lines. Massive architectural changes can warrant longer, detailed messages when the scope justifies it
+* **Use technical language** - Direct, precise, no fluff
 
 ### ❌ DO NOT:
 
-* ❌ **Don't squeeze multiple unrelated changes into a single line** — always separate different types of changes.
-* ❌ **Don't create single-line commit messages when multiple logical groups exist** — use separate lines for each group.
-* ❌ Don't describe the project or its general purpose.
-* ❌ Don't begin with boilerplate like "This commit includes..." or "The following changes..."
-* ❌ Don't use fluffy or celebratory language ("awesome update", "great enhancement").
-* ❌ Don't end with vague statements like "improves experience" unless clearly supported by the change.
-* ❌ Don't use markdown formatting — the output should be plain text only.
-* ❌ **Don't reference or describe previous commits from the log context** — focus only on the current change.
-* ❌ **Don't let the log context influence your commit message content** — it's background information only.
-* ❌ **Don't continue themes or patterns from previous commits** unless they're directly relevant to the current diff.
+* ❌ **NEVER describe changes not in the diff** - This is the #1 failure mode
+* ❌ **NEVER reference log context** - Don't describe "this continues previous work" or similar
+* ❌ **NEVER use vague language** - "Improve", "refactor", "enhance" without specifics
+* ❌ **NEVER write multi-paragraph essays** - Keep it concise
+* ❌ **NEVER mention test changes unless they're significant** - Focus on production code
+* ❌ **NEVER use markdown** - Plain text only
+* ❌ **NEVER begin with "This commit..."** - Just describe what changed
 
 ---
 
-## 📝 OUTPUT STRUCTURE
+## 📝 OUTPUT FORMATS & EXAMPLES
 
-### ✅ DEFAULT FORMAT: Multiline with Bullet Points
+### ✅ GOOD: Concise with file citations (3-6 lines)
 
-**PREFERRED FORMAT** - Use this for most changes, even relatively simple ones:
+> Remove post-publish branch sync and version bump automation
+>
+> * Delete 68 lines of merge/version-bump code from src/commands/publish.ts (lines 1039-1106)
+> * Replace with simple completion message and manual next-steps guidance
+> * Add verbose logging to git tag search in src/util/git.ts for debugging
 
-* A **summary line** describing the overall intent
-* **Bullet points** for each distinct group of changes
-* Each bullet should represent a different logical area (files, functionality, configuration, tests, etc.)
+**Why this is good:** Specific files, line counts, describes what actually changed
 
-#### Example:
+---
 
-> Refactor session handling to use new getUserProfile API
->
-> * Switch from parseUser() to getUserProfile() in session.ts
-> * Update session schema validation in auth.ts
-> * Remove legacy parsing logic from user-utils.ts
-> * Update related tests in session.test.ts
+### ✅ GOOD: Single atomic change (1 line)
 
-#### Example with GitHub Issues Context:
+> Fix typo in error message for invalid credentials in src/auth/validator.ts
 
-> Fix authentication timeout and improve session handling (addresses #145, #167)
->
-> * Increase session timeout from 30min to 2hrs in config.ts (fixes #145)
-> * Add automatic token refresh logic in auth-service.ts (fixes #167)
-> * Update error handling for expired sessions in middleware.ts
-> * Add tests for extended session scenarios in auth.test.ts
+**Why this is good:** One file, one change, specific
 
 ---
 
-### ✅ For Single, Atomic Changes Only
-
-**ONLY use a single line when the change is truly atomic** - affecting one function in one file with one clear purpose:
+### ✅ GOOD: Multiple related changes (4-7 lines)
 
-#### Example:
+> Add retry logic for API timeout errors
+>
+> * Implement exponential backoff in src/api/client.ts
+> * Add max retry configuration to src/config/api.ts
+> * Update error handling in src/api/error-handler.ts to detect retryable errors
+> * Add retry tests in tests/api/client.test.ts
 
-> Fix typo in error message for invalid user credentials
+**Why this is good:** Grounded in actual files, specific changes, concise
 
 ---
 
-### ✅ For Complex or Multi-Part Changes
+### ❌ BAD: Hallucinated changes (DO NOT DO THIS)
+
+> Centralize ref-detection and streamline publish flow
+>
+> * Move to single ref-detection approach and stop passing from/to into Log.create()
+> * Replace ad-hoc fromRef/toRef handling in src/commands/release.ts
+> * Scale diff context: DEFAULT_MAX_DIFF_BYTES now 20480
+> * Update tests to mock new git boundary
+> * Update docs/public/commands/publish.md
 
-For larger changes with significant architectural implications:
+**Why this is terrible:** These changes aren't in the diff! The LLM is describing previous commits from log context instead of the actual diff. This is the #1 failure mode to avoid.
 
-* A **summary paragraph** describing the overall intent
-* One or two **detail paragraphs** focusing on key aspects or trade-offs
-* **Bullet points** to call out specific files, tools, or changes
+---
 
-#### Example:
+### ❌ BAD: Verbose multi-paragraph essay (DO NOT DO THIS)
 
 > Reorganize pipeline logic to improve readability and make phase execution more testable. This is part of ongoing work to modularize transition handling.
 >
 > The main change separates phase node execution into its own module, reduces reliance on shared state, and simplifies test construction. Existing functionality remains unchanged, but internal structure is now better aligned with future transition plugin support.
 >
+> This commit represents a significant cleanup of the execution flow and provides a safer foundation for future operations.
+>
 > * Extract executePhaseNode() from pipeline.ts
 > * Add phase-runner.ts with dedicated error handling
-> * Update tests in phase.test.ts for new isolation boundaries
-> * Refactor shared state management in core.ts
+> ...
+
+**Why this is terrible:** Way too verbose (could be 3 lines), fluffy language, unnecessary context paragraphs
 
 ---
 
-## 🧾 Final Note
+### ❌ BAD: Vague without file citations (DO NOT DO THIS)
+
+> Improve error handling and refactor configuration logic
+
+**Why this is terrible:** No specific files, vague verbs like "improve" and "refactor", no details
+
+---
+
+## 🎯 Length Guidelines
+
+* **Single change:** 1 line
+* **Typical commit:** 3-6 lines (summary + 2-5 bullets)
+* **Large commit:** 6-15 lines
+* **Major architectural change:** Essay-length if warranted (rare but valid)
 
-**DEFAULT TO MULTILINE**: When in doubt, use bullet points to separate different types of changes. This makes commit messages much more scannable and helps reviewers understand the scope of each change group. Only use single-line messages for truly atomic, single-purpose changes.
+**There is no hard upper limit.** The constraint is not length - it's **accuracy**. Every line must describe actual changes from the diff.
 
-Match your output to the **scope and complexity** of the change, but favor clarity and separation over brevity. Your audience is technical and time-constrained — give them clear, well-organized information they can quickly scan.
+Write as much as you need to accurately describe the changes, but no more. A 50-line commit message is fine if the diff touches 30 files and restructures core systems. A 6-line commit message that describes changes not in the diff is a critical failure, regardless of its brevity.

package/dist/prompt/instructions/release.md

@@ -1,12 +1,16 @@
-Task #1: Write release notes by reading all of the log messages from this release and writing a summary of the release.
+## ⚠️ CRITICAL RULES - READ FIRST
 
-Task #2: Provide a detailed list of changes involved in this release, and make sure that the release notes are directly related to the content in the log messages.
+1. **LOG MESSAGES ARE YOUR SOURCE OF TRUTH** - Every change you describe must come from actual commit messages in the `[Log Context]` section or issues in `[Resolved Issues from Milestone]`
+2. **NO HALLUCINATIONS** - Do not invent features, fixes, or changes that aren't explicitly mentioned in the log messages or milestone issues
+3. **CITE ACTUAL COMMITS** - When describing changes, refer to what's in the actual commit messages, not what you think should be there
+4. **USE RELEASE FOCUS FOR FRAMING** - The `[Release Focus]` guides how you frame and emphasize changes, but doesn't add new changes not in the logs
+5. **LENGTH FOLLOWS SCOPE** - Small releases get concise notes. Large releases deserve comprehensive documentation. Match the actual scope of changes in the log
 
-Task #3: Use the content in the Release Focus section as the PRIMARY GUIDE for writing the release notes and to help make connections with people, projects, issues, features, and other information. The Release Focus should heavily influence the tone, emphasis, and structure of your release notes.
+---
 
-Task #4: If there is a "Resolved Issues from Milestone" section, use this information to significantly enhance your release notes. These are well-documented issues that were resolved in this release. Include the important changes from these issues in your release notes, and make sure to reference the issue numbers. Milestone issues represent significant work that users care about and should be prominently featured in the release notes.
+## Your Task
 
-**IMPORTANT**: If you see a "Release Size Context" indicating this is a LARGE RELEASE, you should provide comprehensive, detailed release notes that thoroughly document all changes. For large releases, be extensive rather than brief - users need to understand the full scope of changes. Don't just summarize - dive deep into the details, organize changes into meaningful groups, and explain the impact of major changes.
+Write release notes by reading all commit messages in `[Log Context]` and milestone issues in `[Resolved Issues from Milestone]`. Every change you mention must be traceable to an actual commit message or resolved issue.
 
 ### Output Format
 
@@ -91,19 +95,19 @@ Create release notes that:
 
 3. **Use clear, factual bullet points** under each section. Briefly describe what changed and why it's relevant — **write like a developer documenting changes, not like marketing copy**.
 
+   **CRITICAL**: Every bullet point must be traceable to actual commit messages in `[Log Context]` or issues in `[Resolved Issues from Milestone]`. If a change isn't in the log, don't mention it.
+
    **For large releases**: Provide detailed bullet points that explain:
-   - What specifically changed
+   - What specifically changed (cite actual commit messages)
    - Why the change was made (if evident from commit messages or issue descriptions)
-   - Impact on users or developers
-   - Related files or components affected (when relevant)
+   - Impact on users or developers (based on commit/issue context)
+   - Related files or components affected (when mentioned in commits)
 
-   Avoid vague or exaggerated terms like:
-   * "awesome new feature"
-   * "significant boost"
-   * "exciting changes"
-   * "revolutionary update"
-   * "streamlined workflow"
-   * "enhanced user experience"
+   **DO NOT**:
+   * Invent features not mentioned in commits
+   * Describe changes that "should" be there but aren't in the log
+   * Use vague or exaggerated marketing terms like "awesome new feature", "significant boost", "revolutionary update", "streamlined workflow", "enhanced user experience"
+   * Group unrelated commits under theme names that aren't in the actual commits
 
 4. **Keep your tone technical, neutral, and useful.** It's okay to include references to:
 
@@ -121,22 +125,64 @@ Create release notes that:
 
 ---
 
+## Anti-Examples: What NOT to Do
+
+### ❌ BAD: Hallucinated Changes
+
+**Problem**: The release notes describe features that aren't in any commit message:
+
+```json
+{
+  "title": "Major Performance Overhaul and API Redesign",
+  "body": "**Performance Improvements**\\n\\n* Reduced API response times by 60% through query optimization\\n* Implemented connection pooling for database efficiency\\n* Added Redis caching layer for frequently accessed data\\n\\n**API Redesign**\\n\\n* Completely redesigned REST API with versioning support\\n* Migrated all endpoints to new authentication system"
+}
+```
+
+**Why it's terrible**: None of these changes appear in the commit log. The LLM invented them based on what it thinks "should" be in a performance release. This is a critical failure even if the notes sound good.
+
+---
+
+### ❌ BAD: Vague Marketing Fluff
+
+**Problem**: Generic marketing language instead of specific commit-based changes:
+
+```json
+{
+  "title": "Enhanced User Experience and Streamlined Workflows",
+  "body": "This exciting release brings revolutionary improvements to the user experience! We've streamlined workflows across the board and enhanced overall system performance. Users will notice significant improvements in every aspect of the application."
+}
+```
+
+**Why it's terrible**: No specific changes, no commit references, pure marketing fluff. Completely useless to developers.
+
+---
+
 ## Output Format Examples
 
-### Example for a Large Release:
+### ✅ GOOD: Grounded in Actual Commits
+
+**Scenario**: Log contains commits about removing post-publish sync, adding verbose logging, and fixing a config bug
 
 ```json
 {
-  "title": "Configuration System Overhaul and Developer Tooling v2.1.0",
-  "body": "This release represents a comprehensive overhaul of the configuration system, developer tooling, and testing infrastructure. Based on the Release Focus of modernizing the development workflow and addressing long-standing technical debt, this release includes significant architectural changes, new developer features, and extensive improvements to code quality and maintainability.\\n\\n**Configuration System Overhaul**\\n\\n* Completely redesigned configuration loading system with support for environment-specific overrides\\n* Unified `vite.config.ts`, `webpack.config.js`, and `rollup.config.js` into a single environment-aware configuration module\\n* Added support for `.env.defaults`, `.env.local`, and `.env.production` files with proper precedence handling\\n* Implemented configuration validation with detailed error messages for missing or invalid settings\\n* Migrated from legacy JSON-based config to TypeScript-based configuration with full type safety\\n\\n**New Features**\\n\\n* Added comprehensive CLI argument parsing with support for nested configuration options\\n* Implemented hot-reloading development server with automatic dependency injection\\n* Added support for custom build plugins with a new plugin API\\n* Created new debugging tools including request/response logging and performance profiling\\n* Added automated code formatting and linting with pre-commit hooks\\n\\n**Developer Experience Improvements**\\n\\n* Reduced config nesting depth in `tsconfig.json` to improve readability and maintainability\\n* Updated all development scripts to use the new unified configuration system\\n* Added comprehensive error handling with stack traces and helpful troubleshooting suggestions\\n* Implemented automatic workspace package linking and unlinking for monorepo development\\n* Created new developer documentation with step-by-step setup instructions\\n\\n**Testing Infrastructure**\\n\\n* Migrated entire test suite from Jest to Vitest for better ES module support\\n* Added comprehensive integration tests for the new configuration system\\n* Implemented end-to-end testing with Playwright for critical user workflows\\n* Added test coverage reporting with detailed branch and function coverage metrics\\n* Created performance benchmarks for build times and memory usage\\n\\n**Bug Fixes**\\n\\n* Fixed critical crash in config loader when optional fields were undefined or null\\n* Resolved issue with `yarn build` failing on Windows due to missing path escaping\\n* Fixed memory leak in development server during file watching operations\\n* Corrected TypeScript compilation errors in strict mode for legacy code\\n* Fixed race condition in parallel test execution causing intermittent failures\\n\\n**Breaking Changes**\\n\\n* Removed support for legacy `.env.local.js` files - migrate to `.env.local`\\n* Changed default output directory from `dist/` to `build/` for consistency\\n* Updated minimum Node.js version requirement to 18.0.0\\n* Deprecated `--legacy-config` flag - will be removed in next major version\\n\\n**Documentation Updates**\\n\\n* Completely rewrote setup instructions in `README.md` to reflect new configuration process\\n* Added comprehensive API documentation with examples for all configuration options\\n* Created troubleshooting guide for common development environment issues\\n* Added migration guide for users upgrading from previous versions\\n* Updated all code examples to use the new configuration system"
+  "title": "Simplify publish flow and improve git tag debugging",
+  "body": "**Workflow Changes**\\n\\n* Remove automatic branch sync and version bump from publish flow - users now manually run `kodrdriv development` to continue work after publish\\n* Simplify publish completion to show next steps instead of auto-syncing\\n\\n**Debugging Improvements**\\n\\n* Add extensive logging to git tag detection in `getDefaultFromRef()` to diagnose tag search issues\\n* Add emoji indicators and structured output for tag search process\\n\\n**Bug Fixes**\\n\\n* Fix config validation error when optional field was missing"
 }
 ```
 
-### Example for a Simple Release:
+**Why it's good**: Every bullet point traces to an actual commit. Specific file references. No invented features.
+
+---
+
+### ✅ GOOD: Large Release with Detail
+
+**Scenario**: 30 commits touching configuration system, tests, docs, and CLI
 
 ```json
 {
-  "title": "Simplified Configuration and Windows Build Fixes v1.2.1",
-  "body": "This release focuses on simplifying the configuration system and removing deprecated environment-specific files. Based on the Release Focus of improving developer onboarding and standardizing build behavior, the team prioritized changes that reduce friction for new developers and standardize build behavior across local and CI environments.\\n\\n**Improvements**\\n\\n* Unified `vite.config.ts` and `webpack.config.js` into a single environment-aware module\\n* Reduced config nesting depth in `tsconfig.json` to improve readability\\n* Updated CI scripts to use `.env.defaults` instead of `.env.local`\\n\\n**Bug Fixes**\\n\\n* Fixed crash in config loader when optional fields were undefined\\n* Resolved issue with `yarn build` failing on Windows due to missing path escape\\n\\n**Documentation Updates**\\n\\n* Rewrote setup instructions in `README.md` to reflect unified config process\\n* Removed legacy instructions for `env.local.js`"
+  "title": "Configuration System Overhaul and Testing Migration",
+  "body": "This release modernizes the configuration system and migrates the test suite based on accumulated technical debt and developer feedback.\\n\\n**Configuration System Changes**\\n\\n* Unify vite.config.ts and webpack.config.js into single environment-aware module\\n* Add support for .env.defaults with proper precedence handling\\n* Implement config validation with detailed error messages\\n* Reduce tsconfig.json nesting depth for readability\\n\\n**Testing Infrastructure**\\n\\n* Migrate test suite from Jest to Vitest for better ES module support\\n* Add integration tests for configuration system\\n* Implement coverage reporting with branch and function metrics\\n\\n**Bug Fixes**\\n\\n* Fix crash in config loader when optional fields undefined\\n* Resolve Windows build failure due to missing path escaping\\n* Fix race condition in parallel test execution\\n\\n**Breaking Changes**\\n\\n* Remove support for legacy .env.local.js files\\n* Change default output directory from dist/ to build/\\n* Require Node.js 18.0.0 or higher\\n\\n**Documentation**\\n\\n* Rewrite setup instructions in README.md for new config process\\n* Add migration guide for users upgrading from previous versions"
 }
 ```
+
+**Why it's good**: Comprehensive coverage of a large release, but every change is grounded in actual commits. No fluff, just facts.

package/dist/util/git.js

@@ -56,59 +56,78 @@ import { safeJsonParse, validatePackageJson } from './validation.js';
  * Returns the highest version tag that is less than the current version.
  *
  * @param currentVersion The current version (e.g., "1.2.3", "2.0.0")
+ * @param tagPattern The pattern to match tags (e.g., "v*", "working/v*")
  * @returns The previous release tag or null if none found
- */ const findPreviousReleaseTag = async (currentVersion)=>{
+ */ const findPreviousReleaseTag = async (currentVersion, tagPattern = 'v*')=>{
     const logger = getLogger();
     try {
         // Parse current version first to validate it
         const currentSemver = semver.parse(currentVersion);
         if (!currentSemver) {
-            logger.debug(`Invalid version format: ${currentVersion}`);
+            logger.warn(`❌ Invalid version format: ${currentVersion}`);
             return null;
         }
-        logger.debug(`Looking for previous release tag for version ${currentVersion}`);
+        logger.info(`🔍 findPreviousReleaseTag: Looking for tags matching "${tagPattern}" < ${currentVersion}`);
         // Get all tags - try sorted first, fallback to unsorted
         let tags;
         try {
+            logger.info(`   Running: git tag -l "${tagPattern}" --sort=-version:refname`);
             const { stdout } = await runSecure('git', [
                 'tag',
+                '-l',
+                tagPattern,
                 '--sort=-version:refname'
             ]);
             tags = stdout.trim().split('\n').filter((tag)=>tag.length > 0);
-        } catch  {
+            logger.info(`   ✅ Found ${tags.length} tags matching pattern "${tagPattern}"`);
+            if (tags.length > 0) {
+                logger.info(`   📋 Tags (newest first): ${tags.slice(0, 15).join(', ')}${tags.length > 15 ? ` ... (${tags.length - 15} more)` : ''}`);
+            }
+        } catch (sortError) {
             // Fallback for older git versions that don't support --sort
-            logger.debug('Git tag --sort failed, falling back to manual sorting');
+            logger.info(`   ⚠️  Git tag --sort failed: ${sortError.message}`);
+            logger.info(`   Falling back to manual sorting...`);
             const { stdout } = await runSecure('git', [
-                'tag'
+                'tag',
+                '-l',
+                tagPattern
             ]);
             tags = stdout.trim().split('\n').filter((tag)=>tag.length > 0);
+            logger.info(`   Found ${tags.length} tags (unsorted) matching pattern "${tagPattern}"`);
             // Manual semantic version sorting
             tags.sort((a, b)=>{
-                const aClean = a.startsWith('v') ? a.substring(1) : a;
-                const bClean = b.startsWith('v') ? b.substring(1) : b;
-                const aSemver = semver.parse(aClean);
-                const bSemver = semver.parse(bClean);
-                if (!aSemver && !bSemver) return 0;
-                if (!aSemver) return 1;
-                if (!bSemver) return -1;
-                // Sort in descending order (newest first)
-                return semver.compare(bSemver, aSemver);
+                const aMatch = a.match(/v?(\d+\.\d+\.\d+.*?)$/);
+                const bMatch = b.match(/v?(\d+\.\d+\.\d+.*?)$/);
+                if (!aMatch || !bMatch) return 0;
+                const aSemver = semver.parse(aMatch[1]);
+                const bSemver = semver.parse(bMatch[1]);
+                if (!aSemver || !bSemver) return 0;
+                return semver.rcompare(aSemver, bSemver);
             });
+            logger.info(`   ✅ Sorted ${tags.length} tags manually`);
         }
         if (tags.length === 0) {
-            logger.debug('No tags found in repository');
+            logger.warn('');
+            logger.warn(`❌ NO TAGS FOUND matching pattern "${tagPattern}"`);
+            logger.warn(`   To verify, run: git tag -l '${tagPattern}'`);
+            logger.warn('');
             return null;
         }
-        logger.debug(`Found ${tags.length} tags in repository`);
+        logger.info(`   🔬 Processing ${tags.length} tags to find the highest version < ${currentVersion}...`);
         // Find the highest version that is less than the current version
         let previousTag = null;
         let previousVersion = null;
         let validTags = 0;
         let skippedTags = 0;
         for (const tag of tags){
-            // Remove 'v' prefix if present for parsing
-            const cleanTag = tag.startsWith('v') ? tag.substring(1) : tag;
-            const tagSemver = semver.parse(cleanTag);
+            // Extract version from tag - handle "v1.2.13", "1.2.13", and "working/v1.2.13"
+            const versionMatch = tag.match(/v?(\d+\.\d+\.\d+.*?)$/);
+            if (!versionMatch) {
+                logger.debug(`   ⏭️  Skipping tag "${tag}" (doesn't match version pattern)`);
+                continue;
+            }
+            const versionString = versionMatch[1];
+            const tagSemver = semver.parse(versionString);
             if (tagSemver) {
                 validTags++;
                 // Check if this tag version is less than current version
@@ -116,24 +135,35 @@ import { safeJsonParse, validatePackageJson } from './validation.js';
                     // If we don't have a previous version yet, or this one is higher than our current previous
                     if (!previousVersion || semver.gt(tagSemver, previousVersion)) {
                         previousVersion = tagSemver;
-                        previousTag = tag; // Keep the original tag format (with or without 'v')
-                        logger.debug(`Found candidate previous tag: ${tag} (${tagSemver.version})`);
+                        previousTag = tag; // Keep the original tag format
+                        logger.info(`      ✅ New best candidate: ${tag} (${versionString} < ${currentVersion})`);
+                    } else {
+                        logger.debug(`      ⏭️  ${tag} (${versionString}) is < current but not better than ${previousTag}`);
                     }
                 } else {
                     skippedTags++;
+                    logger.debug(`      ⏭️  ${tag} (${versionString}) >= current (${currentVersion}), skipping`);
                 }
             }
         }
-        logger.debug(`Processed ${validTags} valid semantic version tags, skipped ${skippedTags} tags >= current version`);
+        logger.info('');
+        logger.info(`   📊 Tag analysis results:`);
+        logger.info(`      - Total tags examined: ${tags.length}`);
+        logger.info(`      - Valid semver tags: ${validTags}`);
+        logger.info(`      - Tags >= current version (skipped): ${skippedTags}`);
+        logger.info(`      - Best match: ${previousTag || 'none'}`);
+        logger.info('');
         if (previousTag) {
-            logger.info(`Found previous release tag: ${previousTag} (version: ${previousVersion === null || previousVersion === void 0 ? void 0 : previousVersion.version})`);
-        } else {
-            logger.debug(`No previous release tag found for version ${currentVersion}`);
-            if (validTags > 0) {
-                logger.debug('All existing tags are greater than or equal to current version (likely first release)');
-            }
+            logger.info(`✅ SUCCESS: Found previous tag: ${previousTag}`);
+            logger.info(`   Version comparison: ${previousVersion === null || previousVersion === void 0 ? void 0 : previousVersion.version} < ${currentVersion}`);
+            logger.info('');
+            return previousTag;
         }
-        return previousTag;
+        logger.warn(`❌ FAILED: No previous tag found for version ${currentVersion}`);
+        logger.warn(`   Pattern searched: "${tagPattern}"`);
+        logger.warn(`   Reason: All ${validTags} valid tags were >= ${currentVersion}`);
+        logger.warn('');
+        return null;
     } catch (error) {
         logger.debug(`Error finding previous release tag: ${error.message}`);
         return null;
@@ -181,21 +211,89 @@ import { safeJsonParse, validatePackageJson } from './validation.js';
  * Gets a reliable default for the --from parameter by trying multiple fallbacks
  *
  * Tries in order:
- * 1. Previous release tag (if current version can be determined)
- * 2. main (local main branch - typical release comparison base)
- * 3. master (local master branch - legacy default)
- * 4. origin/main (remote main branch fallback)
- * 5. origin/master (remote master branch fallback)
+ * 1. Previous working branch tag (if on working branch)
+ * 2. Previous release tag (if current version can be determined)
+ * 3. main (local main branch - typical release comparison base)
+ * 4. master (local master branch - legacy default)
+ * 5. origin/main (remote main branch fallback)
+ * 6. origin/master (remote master branch fallback)
  *
  * @param forceMainBranch If true, skip tag detection and use main branch
+ * @param currentBranch Current branch name for branch-aware tag detection
  * @returns A valid git reference to use as the default from parameter
  * @throws Error if no valid reference can be found
- */ const getDefaultFromRef = async (forceMainBranch = false)=>{
+ */ const getDefaultFromRef = async (forceMainBranch = false, currentBranch)=>{
     const logger = getLogger();
+    logger.info('');
+    logger.info('═══════════════════════════════════════════════════════════');
+    logger.info('🔍 DETECTING DEFAULT --from REFERENCE FOR RELEASE NOTES');
+    logger.info('═══════════════════════════════════════════════════════════');
+    logger.info(`📋 Input parameters:`);
+    logger.info(`   - forceMainBranch: ${forceMainBranch}`);
+    logger.info(`   - currentBranch: "${currentBranch}"`);
+    logger.info('');
     // If forced to use main branch, skip tag detection
     if (forceMainBranch) {
-        logger.debug('Forced to use main branch, skipping tag detection');
+        logger.info('⚡ Forced to use main branch, skipping tag detection');
     } else {
+        // If on working branch, look for working branch tags first
+        logger.info(`🎯 Branch check: currentBranch="${currentBranch}", isWorking=${currentBranch === 'working'}`);
+        if (currentBranch && currentBranch === 'working') {
+            logger.info('');
+            logger.info('📍 DETECTED WORKING BRANCH - Searching for working branch tags...');
+            logger.info('───────────────────────────────────────────────────────────');
+            try {
+                const currentVersion = await getCurrentVersion();
+                logger.info(`📦 Current version from package.json: ${currentVersion}`);
+                if (currentVersion) {
+                    logger.info(`🔍 Searching for tags matching pattern: "working/v*"`);
+                    logger.info(`   (Looking for tags < ${currentVersion})`);
+                    logger.info('');
+                    const previousTag = await findPreviousReleaseTag(currentVersion, 'working/v*');
+                    logger.info(`🎯 findPreviousReleaseTag result: ${previousTag || 'null (no tag found)'}`);
+                    if (previousTag) {
+                        logger.info(`🔬 Validating tag reference: "${previousTag}"`);
+                        const isValid = await isValidGitRef(previousTag);
+                        logger.info(`   Tag is valid git ref: ${isValid}`);
+                        if (isValid) {
+                            logger.info('');
+                            logger.info(`✅ SUCCESS: Using previous working branch tag '${previousTag}'`);
+                            logger.info(`   This shows commits added since the last release`);
+                            logger.info('═══════════════════════════════════════════════════════════');
+                            logger.info('');
+                            return previousTag;
+                        } else {
+                            logger.warn('');
+                            logger.warn(`⚠️  VALIDATION FAILED: Tag "${previousTag}" exists but is not a valid git reference`);
+                            logger.warn(`   This should not happen - the tag might be corrupted`);
+                        }
+                    } else {
+                        logger.warn('');
+                        logger.warn('❌ NO WORKING BRANCH TAG FOUND matching pattern "working/v*"');
+                        logger.warn(`   Current version: ${currentVersion}`);
+                        logger.warn('   💡 To create working branch tags for past releases, run:');
+                        logger.warn('      kodrdriv development --create-retroactive-tags');
+                        logger.warn('');
+                        logger.warn('   Falling back to regular tag search...');
+                    }
+                } else {
+                    logger.warn('');
+                    logger.warn('❌ CANNOT READ VERSION from package.json');
+                    logger.warn('   Cannot search for working branch tags without current version');
+                }
+            } catch (error) {
+                logger.warn('');
+                logger.warn(`❌ ERROR while searching for working branch tag: ${error.message}`);
+                logger.debug(`Full error stack: ${error.stack}`);
+                logger.warn('   Falling back to regular tag search...');
+            }
+            logger.info('───────────────────────────────────────────────────────────');
+            logger.info('');
+        } else {
+            logger.info(`ℹ️  Not on "working" branch - skipping working tag search`);
+            logger.info(`   (Only search for working/v* tags when on working branch)`);
+            logger.info('');
+        }
         // First, try to find the previous release tag
         try {
             const currentVersion = await getCurrentVersion();