chore: merge dev to main (v0.22.0)

.cursor/commands/specfact.sync-backlog.md

@@ -20,7 +20,8 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 
 ### Target/Input
 
-- `--repo PATH` - Path to repository. Default: current directory (.)
+- `--repo PATH` - Path to OpenSpec repository containing change proposals. Default: current directory (.)
+- `--code-repo PATH` - Path to source code repository for code change detection (default: same as `--repo`). **Required when OpenSpec repository differs from source code repository.** For example, if OpenSpec proposals are in `specfact-cli-internal` but source code is in `specfact-cli`, use `--repo /path/to/specfact-cli-internal --code-repo /path/to/specfact-cli`.
 - `--target-repo OWNER/REPO` - Target repository for issue creation (format: owner/repo). Default: same as code repository
 
 ### Behavior/Options
@@ -49,6 +50,18 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 - `--tmp-file PATH` - Specify temporary file path (used with --export-to-tmp or --import-from-tmp)
   - Default: `/tmp/specfact-proposal-<change-id>.md` or `/tmp/specfact-proposal-<change-id>-sanitized.md`
 
+### Code Change Tracking (Advanced)
+
+- `--track-code-changes/--no-track-code-changes` - Detect code changes (git commits, file modifications) and add progress comments to existing issues (default: False)
+  - **Repository Selection**: Uses `--code-repo` if provided, otherwise uses `--repo` for code change detection
+  - **Git Commit Detection**: Searches git log for commits mentioning the change proposal ID (e.g., `add-code-change-tracking`)
+  - **File Change Tracking**: Extracts files modified in detected commits
+  - **Progress Comment Generation**: Formats comment with commit details and file changes
+  - **Duplicate Prevention**: Checks against existing comments to avoid duplicates
+  - **Source Tracking Update**: Updates `proposal.md` with progress metadata
+- `--add-progress-comment/--no-add-progress-comment` - Add manual progress comment to existing issues without code change detection (default: False)
+- `--update-existing/--no-update-existing` - Update existing issue bodies when proposal content changes (default: False for safety). Uses content hash to detect changes.
+
 ### Advanced/Configuration
 
 - `--adapter TYPE` - DevOps adapter type (github, ado, linear, jira). Default: github
@@ -101,8 +114,10 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 **For non-sanitized proposals** (direct export):
 
 ```bash
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --no-sanitize --change-ids <id1,id2> \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [--target-repo <owner/repo>] [--repo-owner <owner>] [--repo-name <name>] \
   [--github-token <token>] [--use-gh-cli]
 ```
@@ -111,13 +126,16 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # Step 3a: Export to temporary file for LLM review
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --sanitize --change-ids <id1,id2> \
+  [--code-repo <source-code-path>] \
   --export-to-tmp --tmp-file /tmp/specfact-proposal-<change-id>.md \
   [--target-repo <owner/repo>] [--repo-owner <owner>] [--repo-name <name>] \
   [--github-token <token>] [--use-gh-cli]
 ```
 
+**Note**: When `--code-repo` is provided, code change detection uses that repository. Otherwise, code changes are detected in the OpenSpec repository (`--repo`).
+
 ### Step 4: LLM Sanitization Review (Slash Command Only, For Sanitized Proposals)
 
 **Only execute if sanitization is required**:
@@ -173,6 +191,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 - Show issue URLs and numbers
 - Indicate sanitization status (if applied)
 - List which proposals were sanitized vs exported directly
+- **Show code change tracking results** (if `--track-code-changes` was enabled):
+  - Number of commits detected
+  - Number of progress comments added
+  - Repository used for code change detection (`--code-repo` or `--repo`)
 - **Show filtering warnings** (if proposals were filtered out due to status)
   - Example: `⚠ Filtered out 2 proposal(s) with non-applied status (public repos only sync archived/completed proposals)`
 - Present any warnings or errors
@@ -223,8 +245,9 @@ When in copilot mode, follow this workflow:
 
 ```bash
 # For each sanitized proposal, export to temp file
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <change-id> --export-to-tmp --tmp-file /tmp/specfact-proposal-<change-id>.md \
+  [--code-repo <source-code-path>] \
   [other options]
 ```
 
@@ -293,8 +316,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # Export non-sanitized proposals directly
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <id1,id2> --no-sanitize \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [other options]
 ```
 
@@ -310,8 +335,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # For each approved sanitized proposal, import from temp file and create issue
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <change-id> --import-from-tmp --tmp-file /tmp/specfact-proposal-<change-id>-sanitized.md \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [other options]
 ```
 
@@ -337,6 +364,11 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
    - Display sync results (issues created/updated)
    - Show issue URLs and numbers
    - Indicate which proposals were sanitized vs exported directly
+   - **Show code change tracking results** (if `--track-code-changes` was enabled):
+     - Number of commits detected per proposal
+     - Number of progress comments added per issue
+     - Repository used for code change detection (`--code-repo` or `--repo`)
+     - Example: `✓ Detected 3 commits for 'add-feature-x', added 1 progress comment to issue #123`
    - **Show filtering warnings** (if proposals were filtered out):
      - Public repos: `⚠ Filtered out N proposal(s) with non-applied status (public repos only sync archived/completed proposals)`
      - Internal repos: `⚠ Filtered out N proposal(s) without source tracking entry and inactive status`
@@ -353,6 +385,7 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 Adapter: github
 Repository: nold-ai/specfact-cli-internal
+Code Repository: nold-ai/specfact-cli (separate repo)
 
 Issues Created:
   - #14: Add DevOps Backlog Tracking Integration
@@ -363,6 +396,31 @@ Sanitization: Applied (different repos detected)
 Issue IDs saved to OpenSpec proposal files
 ```
 
+### Success (With Code Change Tracking)
+
+```text
+✓ Successfully synced 3 change proposals
+
+Adapter: github
+Repository: nold-ai/specfact-cli-internal
+Code Repository: nold-ai/specfact-cli (separate repo)
+
+Issues Created:
+  - #14: Add DevOps Backlog Tracking Integration
+  - #15: Add Change Tracking Data Model
+  - #16: Implement OpenSpec Bridge Adapter
+
+Code Change Tracking:
+  - Detected 5 commits for 'add-devops-backlog-tracking'
+  - Added 1 progress comment to issue #14
+  - Detected 3 commits for 'add-change-tracking-datamodel'
+  - Added 1 progress comment to issue #15
+  - No new commits detected for 'implement-openspec-bridge-adapter'
+
+Sanitization: Applied (different repos detected)
+Issue IDs saved to OpenSpec proposal files
+```
+
 ### Error (Missing Token)
 
 ```text

.github/prompts/specfact.sync-backlog.prompt.md

@@ -20,7 +20,8 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 
 ### Target/Input
 
-- `--repo PATH` - Path to repository. Default: current directory (.)
+- `--repo PATH` - Path to OpenSpec repository containing change proposals. Default: current directory (.)
+- `--code-repo PATH` - Path to source code repository for code change detection (default: same as `--repo`). **Required when OpenSpec repository differs from source code repository.** For example, if OpenSpec proposals are in `specfact-cli-internal` but source code is in `specfact-cli`, use `--repo /path/to/specfact-cli-internal --code-repo /path/to/specfact-cli`.
 - `--target-repo OWNER/REPO` - Target repository for issue creation (format: owner/repo). Default: same as code repository
 
 ### Behavior/Options
@@ -49,6 +50,18 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 - `--tmp-file PATH` - Specify temporary file path (used with --export-to-tmp or --import-from-tmp)
   - Default: `/tmp/specfact-proposal-<change-id>.md` or `/tmp/specfact-proposal-<change-id>-sanitized.md`
 
+### Code Change Tracking (Advanced)
+
+- `--track-code-changes/--no-track-code-changes` - Detect code changes (git commits, file modifications) and add progress comments to existing issues (default: False)
+  - **Repository Selection**: Uses `--code-repo` if provided, otherwise uses `--repo` for code change detection
+  - **Git Commit Detection**: Searches git log for commits mentioning the change proposal ID (e.g., `add-code-change-tracking`)
+  - **File Change Tracking**: Extracts files modified in detected commits
+  - **Progress Comment Generation**: Formats comment with commit details and file changes
+  - **Duplicate Prevention**: Checks against existing comments to avoid duplicates
+  - **Source Tracking Update**: Updates `proposal.md` with progress metadata
+- `--add-progress-comment/--no-add-progress-comment` - Add manual progress comment to existing issues without code change detection (default: False)
+- `--update-existing/--no-update-existing` - Update existing issue bodies when proposal content changes (default: False for safety). Uses content hash to detect changes.
+
 ### Advanced/Configuration
 
 - `--adapter TYPE` - DevOps adapter type (github, ado, linear, jira). Default: github
@@ -101,8 +114,10 @@ Sync OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Line
 **For non-sanitized proposals** (direct export):
 
 ```bash
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --no-sanitize --change-ids <id1,id2> \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [--target-repo <owner/repo>] [--repo-owner <owner>] [--repo-name <name>] \
   [--github-token <token>] [--use-gh-cli]
 ```
@@ -111,13 +126,16 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # Step 3a: Export to temporary file for LLM review
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --sanitize --change-ids <id1,id2> \
+  [--code-repo <source-code-path>] \
   --export-to-tmp --tmp-file /tmp/specfact-proposal-<change-id>.md \
   [--target-repo <owner/repo>] [--repo-owner <owner>] [--repo-name <name>] \
   [--github-token <token>] [--use-gh-cli]
 ```
 
+**Note**: When `--code-repo` is provided, code change detection uses that repository. Otherwise, code changes are detected in the OpenSpec repository (`--repo`).
+
 ### Step 4: LLM Sanitization Review (Slash Command Only, For Sanitized Proposals)
 
 **Only execute if sanitization is required**:
@@ -173,6 +191,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 - Show issue URLs and numbers
 - Indicate sanitization status (if applied)
 - List which proposals were sanitized vs exported directly
+- **Show code change tracking results** (if `--track-code-changes` was enabled):
+  - Number of commits detected
+  - Number of progress comments added
+  - Repository used for code change detection (`--code-repo` or `--repo`)
 - **Show filtering warnings** (if proposals were filtered out due to status)
   - Example: `⚠ Filtered out 2 proposal(s) with non-applied status (public repos only sync archived/completed proposals)`
 - Present any warnings or errors
@@ -223,8 +245,9 @@ When in copilot mode, follow this workflow:
 
 ```bash
 # For each sanitized proposal, export to temp file
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <change-id> --export-to-tmp --tmp-file /tmp/specfact-proposal-<change-id>.md \
+  [--code-repo <source-code-path>] \
   [other options]
 ```
 
@@ -293,8 +316,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # Export non-sanitized proposals directly
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <id1,id2> --no-sanitize \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [other options]
 ```
 
@@ -310,8 +335,10 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 ```bash
 # For each approved sanitized proposal, import from temp file and create issue
-specfact sync bridge --adapter github --mode export-only --repo <path> \
+specfact sync bridge --adapter github --mode export-only --repo <openspec-path> \
   --change-ids <change-id> --import-from-tmp --tmp-file /tmp/specfact-proposal-<change-id>-sanitized.md \
+  [--code-repo <source-code-path>] \
+  [--track-code-changes] [--add-progress-comment] \
   [other options]
 ```
 
@@ -337,6 +364,11 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
    - Display sync results (issues created/updated)
    - Show issue URLs and numbers
    - Indicate which proposals were sanitized vs exported directly
+   - **Show code change tracking results** (if `--track-code-changes` was enabled):
+     - Number of commits detected per proposal
+     - Number of progress comments added per issue
+     - Repository used for code change detection (`--code-repo` or `--repo`)
+     - Example: `✓ Detected 3 commits for 'add-feature-x', added 1 progress comment to issue #123`
    - **Show filtering warnings** (if proposals were filtered out):
      - Public repos: `⚠ Filtered out N proposal(s) with non-applied status (public repos only sync archived/completed proposals)`
      - Internal repos: `⚠ Filtered out N proposal(s) without source tracking entry and inactive status`
@@ -353,6 +385,7 @@ specfact sync bridge --adapter github --mode export-only --repo <path> \
 
 Adapter: github
 Repository: nold-ai/specfact-cli-internal
+Code Repository: nold-ai/specfact-cli (separate repo)
 
 Issues Created:
   - #14: Add DevOps Backlog Tracking Integration
@@ -363,6 +396,31 @@ Sanitization: Applied (different repos detected)
 Issue IDs saved to OpenSpec proposal files
 ```
 
+### Success (With Code Change Tracking)
+
+```text
+✓ Successfully synced 3 change proposals
+
+Adapter: github
+Repository: nold-ai/specfact-cli-internal
+Code Repository: nold-ai/specfact-cli (separate repo)
+
+Issues Created:
+  - #14: Add DevOps Backlog Tracking Integration
+  - #15: Add Change Tracking Data Model
+  - #16: Implement OpenSpec Bridge Adapter
+
+Code Change Tracking:
+  - Detected 5 commits for 'add-devops-backlog-tracking'
+  - Added 1 progress comment to issue #14
+  - Detected 3 commits for 'add-change-tracking-datamodel'
+  - Added 1 progress comment to issue #15
+  - No new commits detected for 'implement-openspec-bridge-adapter'
+
+Sanitization: Applied (different repos detected)
+Issue IDs saved to OpenSpec proposal files
+```
+
 ### Error (Missing Token)
 
 ```text