elspais 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

elspais/trace_view/html/templates/partials/review/help/help-panel.json

@@ -0,0 +1,244 @@
+{
+  "version": "1.0",
+  "helpPanel": {
+    "id": "spec-review-help",
+    "title": "Spec Review Help",
+    "sections": [
+      {
+        "id": "how-to",
+        "title": "How Do I...",
+        "icon": "question-circle",
+        "items": [
+          {
+            "id": "start-review",
+            "question": "How do I start reviewing?",
+            "answer": "1. Set your username in the header field\n2. Enable **Review Mode** using the toggle\n3. Select or create a review package\n4. Click on a REQ to start adding comments"
+          },
+          {
+            "id": "add-comment",
+            "question": "How do I add a comment?",
+            "answer": "1. Select a REQ in the tree\n2. Click **Add Comment** in the review panel\n3. Choose a position type (General, Line, Block, or Word)\n4. Write your comment using Markdown\n5. Click **Submit**"
+          },
+          {
+            "id": "comment-on-line",
+            "question": "How do I comment on a specific line?",
+            "answer": "1. Click on the line number in the content view, or\n2. Select **Line** position type and enter the line number\n\nThe comment will be anchored to that line."
+          },
+          {
+            "id": "see-others-comments",
+            "question": "How do I see other reviewers' comments?",
+            "answer": "Click **Fetch All** in the sync controls. This consolidates comments from all reviewers working on the same package."
+          },
+          {
+            "id": "resolve-thread",
+            "question": "How do I resolve a comment thread?",
+            "answer": "Find the thread in the review panel and click **Resolve**. The thread will be marked as resolved but remains visible (faded)."
+          },
+          {
+            "id": "create-package",
+            "question": "How do I create a review package?",
+            "answer": "1. Open the **Review Packages** panel\n2. Click **+ New Package**\n3. Enter a name and description\n4. Click **Create**\n\nYour review branch will be created automatically. You must create a package before adding comments."
+          },
+          {
+            "id": "add-req-to-package",
+            "question": "How do I add a REQ to my package?",
+            "answer": "**Method 1**: Click \"Set to Review\" on any REQ to add it to your active package.\n\n**Method 2**: Use the package controls to manually add/remove REQs."
+          },
+          {
+            "id": "request-status-change",
+            "question": "How do I change a REQ's status?",
+            "answer": "For **Draft → Review**: Click \"Set to Review\" directly.\n\nFor other transitions: Click \"Request Status Change\", select the target status, provide justification, and wait for required approvals."
+          },
+          {
+            "id": "see-original-file",
+            "question": "How do I see a file as it was when a comment was made?",
+            "answer": "When a file has been modified since a comment was made, you'll see a **Modified** badge. Click **Show Original** to view the file at the exact commit when the comment was created."
+          },
+          {
+            "id": "view-archived-package",
+            "question": "How do I view an archived package?",
+            "answer": "1. Scroll to the **Archived Packages** section in the packages panel\n2. Click on any archived package to open the archive viewer\n3. The viewer shows all threads and comments in read-only mode\n\n**Note**: Archived packages cannot be modified or reopened."
+          },
+          {
+            "id": "archive-package-manually",
+            "question": "How do I archive a package manually?",
+            "answer": "1. Click the **Archive** button on the package\n2. Confirm the archival\n\nThe package and all its threads will be moved to the archive. This cannot be undone, but the data is preserved for audit purposes."
+          }
+        ]
+      },
+      {
+        "id": "indicators",
+        "title": "What Does It Mean When...",
+        "icon": "info-circle",
+        "items": [
+          {
+            "id": "modified-badge",
+            "question": "A thread shows 'Modified' (orange badge)?",
+            "answer": "The file has been changed since the comment was made. Line numbers may have shifted.\n\n**Tip**: Click **Show Original** to see the file exactly as it was when the comment was created."
+          },
+          {
+            "id": "position-shifted",
+            "question": "A position shows 'may have shifted'?",
+            "answer": "The file was edited after the comment was made, and line insertions or deletions may have changed the actual line number.\n\nThe system tries to estimate the new position, but click **Show Original** for certainty."
+          },
+          {
+            "id": "version-lost",
+            "question": "A thread shows 'Version Lost' (gray badge)?",
+            "answer": "The original git commit cannot be found. This usually means the commit was part of a branch that was deleted or force-pushed.\n\nThe comment content is preserved, but the original file version cannot be retrieved."
+          },
+          {
+            "id": "sync-pending",
+            "question": "The sync indicator shows 'Pending' (yellow)?",
+            "answer": "You have local changes that haven't been pushed to the remote yet. Click **Push** to sync your changes."
+          },
+          {
+            "id": "sync-behind",
+            "question": "The sync indicator shows 'Behind' (blue arrow)?",
+            "answer": "The remote has changes you haven't fetched yet. Click **Fetch** to pull the latest changes."
+          },
+          {
+            "id": "unanchored-position",
+            "question": "A comment position shows as 'General' unexpectedly?",
+            "answer": "The original anchor (line, block, or word) could not be found due to significant file changes. The comment was \"unanchored\" and now applies to the whole REQ.\n\nClick **Show Original** to see where the comment was originally placed."
+          },
+          {
+            "id": "thread-resolved",
+            "question": "A thread appears faded?",
+            "answer": "The thread has been resolved. It's still visible for reference but the issue has been addressed.\n\nClick **Reopen** if further discussion is needed."
+          },
+          {
+            "id": "approval-pending",
+            "question": "A status request shows 'Pending'?",
+            "answer": "The status change is awaiting approvals from required approvers. Check the request details to see who needs to approve."
+          },
+          {
+            "id": "package-archived",
+            "question": "A package shows 'Archived'?",
+            "answer": "The package has been archived and is read-only. Packages are archived when:\n\n- All threads are resolved (auto-archive)\n- The package was manually archived\n- The package was deleted\n\nView archived packages in the **Archived Packages** section."
+          },
+          {
+            "id": "read-only-notice",
+            "question": "I see 'Read Only' in the review panel?",
+            "answer": "You are viewing an archived package. Archived packages preserve the complete review history but cannot be modified.\n\nTo continue reviewing, select an active package or create a new one."
+          }
+        ]
+      },
+      {
+        "id": "troubleshooting",
+        "title": "Troubleshooting",
+        "icon": "exclamation-triangle",
+        "items": [
+          {
+            "id": "cant-see-comments",
+            "question": "I can't see other users' comments",
+            "answer": "1. Click **Fetch All** to consolidate from all branches\n2. Ensure other reviewers have pushed their changes\n3. Verify you're on the correct package\n4. Check the **Contributors** list to see who has reviewed"
+          },
+          {
+            "id": "sync-failing",
+            "question": "Git sync is failing",
+            "answer": "1. Check your network connection\n2. Verify git credentials are configured\n3. Try manual sync: `git push origin HEAD`\n4. Check for merge conflicts in `.reviews/` directory\n5. Contact your team lead if issues persist"
+          },
+          {
+            "id": "wrong-position",
+            "question": "My comment is showing at the wrong position",
+            "answer": "The file was likely modified after your comment was made.\n\n1. Click **Show Original** to see the exact original position\n2. Check the **diff** info to understand what changed\n3. Create a new comment at the correct position if needed"
+          },
+          {
+            "id": "status-wont-change",
+            "question": "I can't change a REQ's status",
+            "answer": "1. Some transitions require approvals - check if you need to request rather than directly change\n2. Verify you have permission for this transition\n3. Check if there's already a pending request for this REQ\n4. Review the **Status Transitions** table for allowed transitions"
+          },
+          {
+            "id": "package-not-visible",
+            "question": "I can't find my package",
+            "answer": "1. Check the **Review Packages** panel (left sidebar)\n2. Ensure Review Mode is enabled\n3. Try clicking **Fetch** to pull remote branches\n4. The package may have been deleted by another user"
+          },
+          {
+            "id": "comment-disappeared",
+            "question": "My comment seems to have disappeared",
+            "answer": "1. Check if you're on the correct package/branch\n2. Click **Fetch** to sync with remote\n3. Verify the comment was successfully submitted (check for error messages)\n4. The thread may have been resolved - check the resolved threads section"
+          },
+          {
+            "id": "branch-conflict",
+            "question": "I'm getting git conflicts",
+            "answer": "Each reviewer should work on their own branch: `reviews/{package}/{username}`\n\nIf you see conflicts:\n1. Check if someone else used your username\n2. Pull and resolve conflicts manually\n3. Contact your team to coordinate"
+          }
+        ]
+      },
+      {
+        "id": "concepts",
+        "title": "Key Concepts",
+        "icon": "book",
+        "items": [
+          {
+            "id": "what-is-package",
+            "question": "What is a review package?",
+            "answer": "A **package** groups related REQs for a review session. Examples:\n\n- Sprint reviews\n- Release preparation\n- Feature-specific reviews\n\nEach package has its own set of branches, one per reviewer."
+          },
+          {
+            "id": "what-is-thread",
+            "question": "What is a comment thread?",
+            "answer": "A **thread** is a conversation about a specific part of a REQ. It includes:\n\n- **Position**: Where in the REQ (line, block, word, or general)\n- **Comments**: One or more replies\n- **Resolved Status**: Whether the issue is addressed\n- **Version Info**: Git commit when created"
+          },
+          {
+            "id": "position-types",
+            "question": "What are the position types?",
+            "answer": "- **General**: Comment on the whole REQ\n- **Line**: Comment on a specific line number\n- **Block**: Comment on a range of lines (start to end)\n- **Word**: Comment on a specific word or phrase"
+          },
+          {
+            "id": "branch-model",
+            "question": "How does the branch model work?",
+            "answer": "Each reviewer works on their own branch:\n\n```\nreviews/{package-id}/alice\nreviews/{package-id}/bob\nreviews/{package-id}/charlie\n```\n\nThis prevents merge conflicts during active review. Use **Fetch All** to see consolidated comments."
+          },
+          {
+            "id": "version-tracking",
+            "question": "How does version tracking work?",
+            "answer": "When you create a comment, the system records the git commit and file hash.\n\nIf the file changes later:\n- A **Modified** badge appears\n- Line positions may shift\n- You can click **Show Original** to see the file at the comment's commit\n- Diff info shows lines added/removed"
+          },
+          {
+            "id": "status-workflow",
+            "question": "What is the status workflow?",
+            "answer": "REQs progress through statuses:\n\n**Draft** → **Review** → **Active** → **Deprecated**\n\n- Draft → Review: Direct (adds to package)\n- Review → Active: Requires approvals\n- Active → Deprecated: Requires approval"
+          },
+          {
+            "id": "approvals",
+            "question": "How do approvals work?",
+            "answer": "Some status transitions require approvals from designated approvers:\n\n- **product_owner**: Business decisions\n- **tech_lead**: Technical validation\n\nWhen you request a status change, required approvers are notified and must approve before the change is applied."
+          },
+          {
+            "id": "what-is-archive",
+            "question": "What happens when a package is archived?",
+            "answer": "**Archival** preserves the complete review history:\n\n- All threads and comments are saved\n- Git audit trail (branch, commits) is recorded\n- The reason for archival is noted\n\n**Auto-archive triggers**:\n- All threads resolved → reason: \"resolved\"\n- Package deleted → reason: \"deleted\"\n- Manual archive → reason: \"manual\"\n\nArchived data is stored in `.reviews/archive/` and visible in the Archived Packages section."
+          },
+          {
+            "id": "git-audit-trail",
+            "question": "What is the git audit trail?",
+            "answer": "Each package tracks:\n\n- **Branch Name**: The review branch\n- **Creation Commit**: Git hash when package was created\n- **Last Review Commit**: Most recent commit with review activity\n\nThis enables tracing reviews back to specific code versions.\n\n**Note**: Commits may be squashed on merge. The recorded hashes may no longer exist in the main branch history."
+          }
+        ]
+      }
+    ],
+    "footer": {
+      "text": "Need more help? See the full documentation.",
+      "links": [
+        {
+          "label": "User Guide",
+          "url": "docs/spec-review-user-guide.md"
+        },
+        {
+          "label": "Quick Start",
+          "url": "docs/spec-review-quick-start.md"
+        },
+        {
+          "label": "Reference",
+          "url": "docs/spec-review-reference.md"
+        }
+      ]
+    },
+    "settings": {
+      "searchable": true,
+      "collapsible": true,
+      "defaultExpanded": ["how-to"]
+    }
+  }
+}

elspais/trace_view/html/templates/partials/review/help/onboarding.json

@@ -0,0 +1,77 @@
+{
+  "version": "1.0",
+  "wizard": {
+    "id": "spec-review-onboarding",
+    "title": "Welcome to Spec Review",
+    "steps": [
+      {
+        "id": "welcome",
+        "title": "Welcome to Spec Review!",
+        "content": "This tool helps teams collaborate on requirement documents through comments, status changes, and approval workflows.\n\nAll your work is automatically saved and synced via git.",
+        "highlight": null,
+        "position": "center",
+        "buttons": {
+          "next": "Get Started"
+        }
+      },
+      {
+        "id": "username",
+        "title": "Set Your Username",
+        "content": "Your username identifies your comments and creates your personal review branch.\n\nEnter your name or handle in the username field.\n\nYour branch will be: reviews/{package}/{username}",
+        "highlight": "#username-field",
+        "position": "below",
+        "buttons": {
+          "back": "Back",
+          "next": "Next"
+        }
+      },
+      {
+        "id": "packages",
+        "title": "Review Packages",
+        "content": "Packages group related REQs for review. Common uses:\n\n- Sprint reviews\n- Release preparation\n- Feature-specific reviews\n\nCreate a package first, then add REQs and comments to it. Packages can be archived when complete.",
+        "highlight": ".review-packages-panel",
+        "position": "right",
+        "buttons": {
+          "back": "Back",
+          "next": "Next"
+        }
+      },
+      {
+        "id": "comments",
+        "title": "Adding Comments",
+        "content": "Click any REQ, then use the review panel to add comments.\n\nComment types:\n- **General**: Whole REQ\n- **Line**: Specific line\n- **Block**: Line range\n- **Word**: Specific text\n\nComments are git-backed and collaborative!",
+        "highlight": ".rs-panel",
+        "position": "left",
+        "buttons": {
+          "back": "Back",
+          "next": "Next"
+        }
+      },
+      {
+        "id": "collaboration",
+        "title": "Working Together",
+        "content": "Each reviewer has their own branch:\n\n  reviews/my-package/alice\n  reviews/my-package/bob\n\nClick \"Fetch All\" to see everyone's comments merged together.\n\nResolve threads when issues are addressed.",
+        "highlight": ".rs-sync-controls",
+        "position": "below",
+        "buttons": {
+          "back": "Back",
+          "next": "Start Reviewing"
+        }
+      }
+    ],
+    "completion": {
+      "title": "You're Ready!",
+      "content": "You've completed the quick tour. Here are some tips:\n\n- Click the **?** icon anytime for help\n- Hover over controls for tooltips\n- Check the User Guide for detailed info\n\nHappy reviewing!",
+      "buttons": {
+        "close": "Start Reviewing",
+        "docs": "View User Guide"
+      }
+    },
+    "settings": {
+      "showOnFirstVisit": true,
+      "canSkip": true,
+      "canReplay": true,
+      "storageKey": "spec-review-onboarding-complete"
+    }
+  }
+}

elspais/trace_view/html/templates/partials/review/help/tooltips.json

@@ -0,0 +1,237 @@
+{
+  "version": "1.0",
+  "tooltips": {
+    "header": {
+      "review-mode-toggle": {
+        "title": "Review Mode",
+        "text": "Enable to access comment threads, status changes, and collaborative review features."
+      },
+      "username-field": {
+        "title": "Your Username",
+        "text": "Your username identifies your comments and creates your personal review branch: reviews/{package}/{username}"
+      },
+      "package-context-badge": {
+        "title": "Active Package",
+        "text": "Shows which review package you're currently working in. All comments will be associated with this package."
+      },
+      "package-filter-toggle": {
+        "title": "Package Filter",
+        "text": "When enabled, only shows REQs that are in the active package."
+      }
+    },
+    "packages-panel": {
+      "packages-header": {
+        "title": "Review Packages",
+        "text": "Packages group related REQs for review. Create packages for sprints, releases, or feature reviews."
+      },
+      "new-package-button": {
+        "title": "Create Package",
+        "text": "Create a new review package. You'll be prompted for a name and description."
+      },
+      "package-item": {
+        "title": "Package",
+        "text": "Click to activate this package. Your branch will switch to reviews/{package-id}/{username}."
+      },
+      "package-req-count": {
+        "title": "REQ Count",
+        "text": "Number of requirements included in this package."
+      },
+      "archive-button": {
+        "title": "Archive Package",
+        "text": "Move this package to the archive. All threads and comments are preserved for audit purposes."
+      },
+      "archived-packages-section": {
+        "title": "Archived Packages",
+        "text": "Previously archived packages. Click to view in read-only mode."
+      },
+      "archive-reason-resolved": {
+        "title": "Archived: Resolved",
+        "text": "This package was automatically archived when all threads were resolved."
+      },
+      "archive-reason-deleted": {
+        "title": "Archived: Deleted",
+        "text": "This package was archived when deleted. The review data is preserved."
+      },
+      "archive-reason-manual": {
+        "title": "Archived: Manual",
+        "text": "This package was manually archived by a user."
+      }
+    },
+    "comment-form": {
+      "position-type-general": {
+        "title": "General Position",
+        "text": "Comment applies to the entire requirement. Use for high-level feedback."
+      },
+      "position-type-line": {
+        "title": "Line Position",
+        "text": "Anchor your comment to a specific line number. Click a line in the content view to pre-fill."
+      },
+      "position-type-block": {
+        "title": "Block Position",
+        "text": "Anchor your comment to a range of lines. Enter start and end line numbers."
+      },
+      "position-type-word": {
+        "title": "Word Position",
+        "text": "Anchor your comment to a specific word or phrase. Enter the exact text to find."
+      },
+      "line-number-input": {
+        "title": "Line Number",
+        "text": "Enter the 1-based line number. You can also click directly on a line in the content view."
+      },
+      "block-start-input": {
+        "title": "Start Line",
+        "text": "First line of the block you're commenting on."
+      },
+      "block-end-input": {
+        "title": "End Line",
+        "text": "Last line of the block you're commenting on."
+      },
+      "keyword-input": {
+        "title": "Keyword/Phrase",
+        "text": "Enter the exact word or phrase to anchor to. Case-sensitive."
+      },
+      "occurrence-input": {
+        "title": "Occurrence",
+        "text": "If the word appears multiple times, which occurrence? (1 = first occurrence)"
+      },
+      "comment-body": {
+        "title": "Comment Text",
+        "text": "Write your comment using Markdown formatting. Preview is shown below."
+      },
+      "submit-button": {
+        "title": "Submit Comment",
+        "text": "Save your comment. It will be committed to git and synced automatically."
+      }
+    },
+    "thread-display": {
+      "position-label": {
+        "title": "Comment Position",
+        "text": "Click to highlight this location in the REQ content."
+      },
+      "position-warning": {
+        "title": "Position May Be Stale",
+        "text": "The file has changed since this comment was made. The line number may have shifted."
+      },
+      "version-badge-modified": {
+        "title": "File Modified",
+        "text": "The file has changed since this comment was made. Click 'Show Original' to see the original context."
+      },
+      "version-badge-unavailable": {
+        "title": "Version Unavailable",
+        "text": "Cannot retrieve the original file version. The git commit may no longer exist."
+      },
+      "show-original-button": {
+        "title": "Show Original",
+        "text": "View the file exactly as it was when this comment was made."
+      },
+      "show-current-button": {
+        "title": "Show Current",
+        "text": "Return to viewing the current version of the file."
+      },
+      "resolve-button": {
+        "title": "Resolve Thread",
+        "text": "Mark this thread as resolved when the issue has been addressed."
+      },
+      "reopen-button": {
+        "title": "Reopen Thread",
+        "text": "Reopen this resolved thread if further discussion is needed."
+      },
+      "reply-button": {
+        "title": "Reply",
+        "text": "Add a response to this thread."
+      }
+    },
+    "status-panel": {
+      "current-status": {
+        "title": "Current Status",
+        "text": "The current status of this REQ as recorded in the spec file."
+      },
+      "set-to-review-button": {
+        "title": "Set to Review",
+        "text": "Change status to 'Review' and add this REQ to your active package."
+      },
+      "request-status-change": {
+        "title": "Request Status Change",
+        "text": "Request a formal status change that requires approval from designated approvers."
+      },
+      "pending-request": {
+        "title": "Pending Request",
+        "text": "A status change has been requested and is awaiting approvals."
+      },
+      "approve-button": {
+        "title": "Approve",
+        "text": "Approve this status change request."
+      },
+      "reject-button": {
+        "title": "Reject",
+        "text": "Reject this status change request."
+      }
+    },
+    "sync-controls": {
+      "sync-status-synced": {
+        "title": "Synced",
+        "text": "All your changes have been committed and pushed to the remote."
+      },
+      "sync-status-pending": {
+        "title": "Changes Pending",
+        "text": "You have local changes that haven't been pushed yet."
+      },
+      "sync-status-behind": {
+        "title": "Behind Remote",
+        "text": "The remote has changes you haven't fetched yet."
+      },
+      "fetch-button": {
+        "title": "Fetch",
+        "text": "Pull the latest changes from the remote for your branch."
+      },
+      "push-button": {
+        "title": "Push",
+        "text": "Push your local changes to the remote."
+      },
+      "fetch-all-button": {
+        "title": "Fetch All",
+        "text": "Fetch and merge comments from all contributors to this package."
+      },
+      "contributors-list": {
+        "title": "Contributors",
+        "text": "Users who have contributed to reviewing this package."
+      }
+    },
+    "original-view": {
+      "original-banner": {
+        "title": "Original View",
+        "text": "You are viewing the file as it was when the comment was made. This is read-only."
+      },
+      "diff-stats": {
+        "title": "Changes Since Comment",
+        "text": "Shows how many lines were added and removed since the comment was made."
+      }
+    },
+    "archive-viewer": {
+      "archive-badge": {
+        "title": "Archived",
+        "text": "This package has been archived and is read-only."
+      },
+      "archive-meta-branch": {
+        "title": "Branch",
+        "text": "The git branch where this review was conducted."
+      },
+      "archive-meta-created": {
+        "title": "Created",
+        "text": "Git commit hash when the package was created."
+      },
+      "archive-meta-last-reviewed": {
+        "title": "Last Reviewed",
+        "text": "Git commit hash of the most recent review activity."
+      },
+      "commit-squash-warning": {
+        "title": "Commit Hash Warning",
+        "text": "This commit may have been squashed during merge. The hash may no longer exist in the main branch."
+      },
+      "archive-close-button": {
+        "title": "Close Archive Viewer",
+        "text": "Return to the active review panel."
+      }
+    }
+  }
+}