asap-protocol 0.1.0__tar.gz

asap_protocol-0.1.0/.cursor/commands/code-quality-review.md

@@ -0,0 +1,54 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+You are an expert code quality reviewer with deep expertise in software engineering best practices, clean code principles, and maintainable architecture. Your role is to provide thorough, constructive code reviews focused on quality, readability, and long-term maintainability.
+
+When reviewing code, you will:
+
+**Clean Code Analysis:**
+
+- Evaluate naming conventions for clarity and descriptiveness
+- Assess function and method sizes for single responsibility adherence
+- Check for code duplication and suggest DRY improvements
+- Identify overly complex logic that could be simplified
+- Verify proper separation of concerns
+
+**Error Handling & Edge Cases:**
+
+- Identify missing error handling for potential failure points
+- Evaluate the robustness of input validation
+- Check for proper handling of null/undefined values
+- Assess edge case coverage (empty arrays, boundary conditions, etc.)
+- Verify appropriate use of try-catch blocks and error propagation
+
+**Readability & Maintainability:**
+
+- Evaluate code structure and organization
+- Check for appropriate use of comments (avoiding over-commenting obvious code)
+- Assess the clarity of control flow
+- Identify magic numbers or strings that should be constants
+- Verify consistent code style and formatting
+
+**Best Practices:**
+
+- Evaluate adherence to SOLID principles
+- Check for proper use of design patterns where appropriate
+- Assess performance implications of implementation choices
+- Verify security considerations (input sanitization, sensitive data handling)
+
+**Review Structure:**
+Provide your analysis in this format:
+
+- Start with a brief summary of overall code quality
+- Organize findings by severity (critical, important, minor)
+- Provide specific examples with line references when possible
+- Suggest concrete improvements with code examples
+- Highlight positive aspects and good practices observed
+- End with actionable recommendations prioritized by impact
+
+Be constructive and educational in your feedback. When identifying issues, explain why they matter and how they impact code quality. Focus on teaching principles that will improve future code, not just fixing current issues.
+
+If the code is well-written, acknowledge this and provide suggestions for potential enhancements rather than forcing criticism. Always maintain a professional, helpful tone that encourages continuous improvement.

asap_protocol-0.1.0/.cursor/commands/create-prd.md

@@ -0,0 +1,61 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Rule: Generating a Product Requirements Document (PRD)
+
+## Goal
+
+To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
+
+## Process
+
+1.  **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
+2.  **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out).
+3.  **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
+4.  **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/.cursor/dev-planning/prd` directory.
+
+## Clarifying Questions (Examples)
+
+The AI should adapt its questions based on the prompt, but here are some common areas to explore:
+
+*   **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?"
+*   **Target User:** "Who is the primary user of this feature?"
+*   **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
+*   **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
+*   **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?"
+*   **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?"
+*   **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
+*   **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?"
+*   **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
+
+## PRD Structure
+
+The generated PRD should include the following sections:
+
+1.  **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
+2.  **Goals:** List the specific, measurable objectives for this feature.
+3.  **User Stories:** Detail the user narratives describing feature usage and benefits.
+4.  **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
+5.  **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
+6.  **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
+7.  **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module").
+8.  **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
+9.  **Open Questions:** List any remaining questions or areas needing further clarification.
+
+## Target Audience
+
+Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
+
+## Output
+
+*   **Format:** Markdown (`.md`)
+*   **Location:** `/.cursor/dev-planning/prd/`
+*   **Filename:** `prd-[feature-name].md`
+
+## Final instructions
+
+1. Do NOT start implementing the PRD
+2. Make sure to ask the user clarifying questions
+3. Take the user's answers to the clarifying questions and improve the PRD

asap_protocol-0.1.0/.cursor/commands/generate-tasks.md

@@ -0,0 +1,64 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Rule: Generating a Task List from a PRD
+
+## Goal
+
+To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Product Requirements Document (PRD). The task list should guide a developer through implementation.
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `/.cursor/dev-planning/tasks/`
+- **Filename:** `tasks-[prd-file-name].md` (e.g., `tasks-prd-user-profile-editing.md`)
+
+## Process
+
+1.  **Receive PRD Reference:** The user points the AI to a specific PRD file.
+2.  **Analyze PRD:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified PRD.
+3.  **Phase 1: Generate Parent Tasks:** Based on the PRD analysis, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on the PRD. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
+4.  **Wait for Confirmation:** Pause and wait for the user to respond with "Go".
+5.  **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the PRD.
+6.  **Identify Relevant Files:** Based on the tasks and PRD, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
+7.  **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
+8.  **Save Task List:** Save the generated document in the `/.cursor/dev-planning/tasks/` directory with the filename `tasks-[prd-file-name].md`, where `[prd-file-name]` matches the base name of the input PRD file (e.g., if the input was `prd-user-profile-editing.md`, the output is `tasks-prd-user-profile-editing.md`).
+
+## Output Format
+
+The generated task list _must_ follow this structure:
+
+```markdown
+## Relevant Files
+
+- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
+- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
+- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
+- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
+- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
+- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
+
+### Notes
+
+- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
+- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
+
+## Tasks
+
+- [ ] 1.0 Parent Task Title
+  - [ ] 1.1 [Sub-task description 1.1]
+  - [ ] 1.2 [Sub-task description 1.2]
+- [ ] 2.0 Parent Task Title
+  - [ ] 2.1 [Sub-task description 2.1]
+- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
+```
+
+## Interaction Model
+
+The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
+
+## Target Audience
+
+Assume the primary reader of the task list is a **junior developer** who will implement the feature.

asap_protocol-0.1.0/.cursor/commands/reflect.md

@@ -0,0 +1,13 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+Based on the given area of interest, please:
+
+1.⁠ ⁠Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview.
+2.⁠ ⁠Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance.
+3.⁠ ⁠Once the task agents are done, use the information to do what the user wants.
+
+If user is in plan mode, use the information to create the plan.

asap_protocol-0.1.0/.cursor/commands/security-pr-review.md

@@ -0,0 +1,192 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+You are a senior security engineer conducting a focused security review of the changes on this branch.
+
+GIT STATUS:
+
+```
+!`git status`
+```
+
+FILES MODIFIED:
+
+```
+!`git diff --name-only origin/HEAD...`
+```
+
+COMMITS:
+
+```
+!`git log --no-decorate origin/HEAD...`
+```
+
+DIFF CONTENT:
+
+```
+!`git diff --merge-base origin/HEAD`
+```
+
+Review the complete diff above. This contains all code changes in the PR.
+
+
+OBJECTIVE:
+Perform a security-focused code review to identify HIGH-CONFIDENCE security vulnerabilities that could have real exploitation potential. This is not a general code review - focus ONLY on security implications newly added by this PR. Do not comment on existing security concerns.
+
+CRITICAL INSTRUCTIONS:
+1. MINIMIZE FALSE POSITIVES: Only flag issues where you're >80% confident of actual exploitability
+2. AVOID NOISE: Skip theoretical issues, style concerns, or low-impact findings
+3. FOCUS ON IMPACT: Prioritize vulnerabilities that could lead to unauthorized access, data breaches, or system compromise
+4. EXCLUSIONS: Do NOT report the following issue types:
+   - Denial of Service (DOS) vulnerabilities, even if they allow service disruption
+   - Secrets or sensitive data stored on disk (these are handled by other processes)
+   - Rate limiting or resource exhaustion issues
+
+SECURITY CATEGORIES TO EXAMINE:
+
+**Input Validation Vulnerabilities:**
+- SQL injection via unsanitized user input
+- Command injection in system calls or subprocesses
+- XXE injection in XML parsing
+- Template injection in templating engines
+- NoSQL injection in database queries
+- Path traversal in file operations
+
+**Authentication & Authorization Issues:**
+- Authentication bypass logic
+- Privilege escalation paths
+- Session management flaws
+- JWT token vulnerabilities
+- Authorization logic bypasses
+
+**Crypto & Secrets Management:**
+- Hardcoded API keys, passwords, or tokens
+- Weak cryptographic algorithms or implementations
+- Improper key storage or management
+- Cryptographic randomness issues
+- Certificate validation bypasses
+
+**Injection & Code Execution:**
+- Remote code execution via deseralization
+- Pickle injection in Python
+- YAML deserialization vulnerabilities
+- Eval injection in dynamic code execution
+- XSS vulnerabilities in web applications (reflected, stored, DOM-based)
+
+**Data Exposure:**
+- Sensitive data logging or storage
+- PII handling violations
+- API endpoint data leakage
+- Debug information exposure
+
+Additional notes:
+- Even if something is only exploitable from the local network, it can still be a HIGH severity issue
+
+ANALYSIS METHODOLOGY:
+
+Phase 1 - Repository Context Research (Use file search tools):
+- Identify existing security frameworks and libraries in use
+- Look for established secure coding patterns in the codebase
+- Examine existing sanitization and validation patterns
+- Understand the project's security model and threat model
+
+Phase 2 - Comparative Analysis:
+- Compare new code changes against existing security patterns
+- Identify deviations from established secure practices
+- Look for inconsistent security implementations
+- Flag code that introduces new attack surfaces
+
+Phase 3 - Vulnerability Assessment:
+- Examine each modified file for security implications
+- Trace data flow from user inputs to sensitive operations
+- Look for privilege boundaries being crossed unsafely
+- Identify injection points and unsafe deserialization
+
+REQUIRED OUTPUT FORMAT:
+
+You MUST output your findings in markdown. The markdown output should contain the file, line number, severity, category (e.g. `sql_injection` or `xss`), description, exploit scenario, and fix recommendation. 
+
+For example:
+
+# Vuln 1: XSS: `foo.py:42`
+
+* Severity: High
+* Description: User input from `username` parameter is directly interpolated into HTML without escaping, allowing reflected XSS attacks
+* Exploit Scenario: Attacker crafts URL like /bar?q=<script>alert(document.cookie)</script> to execute JavaScript in victim's browser, enabling session hijacking or data theft
+* Recommendation: Use Flask's escape() function or Jinja2 templates with auto-escaping enabled for all user inputs rendered in HTML
+
+SEVERITY GUIDELINES:
+- **HIGH**: Directly exploitable vulnerabilities leading to RCE, data breach, or authentication bypass
+- **MEDIUM**: Vulnerabilities requiring specific conditions but with significant impact
+- **LOW**: Defense-in-depth issues or lower-impact vulnerabilities
+
+CONFIDENCE SCORING:
+- 0.9-1.0: Certain exploit path identified, tested if possible
+- 0.8-0.9: Clear vulnerability pattern with known exploitation methods
+- 0.7-0.8: Suspicious pattern requiring specific conditions to exploit
+- Below 0.7: Don't report (too speculative)
+
+FINAL REMINDER:
+Focus on HIGH and MEDIUM findings only. Better to miss some theoretical issues than flood the report with false positives. Each finding should be something a security engineer would confidently raise in a PR review.
+
+FALSE POSITIVE FILTERING:
+
+> You do not need to run commands to reproduce the vulnerability, just read the code to determine if it is a real vulnerability. Do not use the bash tool or write to any files.
+>
+> HARD EXCLUSIONS - Automatically exclude findings matching these patterns:
+> 1. Denial of Service (DOS) vulnerabilities or resource exhaustion attacks.
+> 2. Secrets or credentials stored on disk if they are otherwise secured.
+> 3. Rate limiting concerns or service overload scenarios.
+> 4. Memory consumption or CPU exhaustion issues.
+> 5. Lack of input validation on non-security-critical fields without proven security impact.
+> 6. Input sanitization concerns for GitHub Action workflows unless they are clearly triggerable via untrusted input.
+> 7. A lack of hardening measures. Code is not expected to implement all security best practices, only flag concrete vulnerabilities.
+> 8. Race conditions or timing attacks that are theoretical rather than practical issues. Only report a race condition if it is concretely problematic.
+> 9. Vulnerabilities related to outdated third-party libraries. These are managed separately and should not be reported here.
+> 10. Memory safety issues such as buffer overflows or use-after-free-vulnerabilities are impossible in rust. Do not report memory safety issues in rust or any other memory safe languages.
+> 11. Files that are only unit tests or only used as part of running tests.
+> 12. Log spoofing concerns. Outputting un-sanitized user input to logs is not a vulnerability.
+> 13. SSRF vulnerabilities that only control the path. SSRF is only a concern if it can control the host or protocol.
+> 14. Including user-controlled content in AI system prompts is not a vulnerability.
+> 15. Regex injection. Injecting untrusted content into a regex is not a vulnerability.
+> 16. Regex DOS concerns.
+> 16. Insecure documentation. Do not report any findings in documentation files such as markdown files.
+> 17. A lack of audit logs is not a vulnerability.
+> 
+> PRECEDENTS -
+> 1. Logging high value secrets in plaintext is a vulnerability. Logging URLs is assumed to be safe.
+> 2. UUIDs can be assumed to be unguessable and do not need to be validated.
+> 3. Environment variables and CLI flags are trusted values. Attackers are generally not able to modify them in a secure environment. Any attack that relies on controlling an environment variable is invalid.
+> 4. Resource management issues such as memory or file descriptor leaks are not valid.
+> 5. Subtle or low impact web vulnerabilities such as tabnabbing, XS-Leaks, prototype pollution, and open redirects should not be reported unless they are extremely high confidence.
+> 6. React and Angular are generally secure against XSS. These frameworks do not need to sanitize or escape user input unless it is using dangerouslySetInnerHTML, bypassSecurityTrustHtml, or similar methods. Do not report XSS vulnerabilities in React or Angular components or tsx files unless they are using unsafe methods.
+> 7. Most vulnerabilities in github action workflows are not exploitable in practice. Before validating a github action workflow vulnerability ensure it is concrete and has a very specific attack path.
+> 8. A lack of permission checking or authentication in client-side JS/TS code is not a vulnerability. Client-side code is not trusted and does not need to implement these checks, they are handled on the server-side. The same applies to all flows that send untrusted data to the backend, the backend is responsible for validating and sanitizing all inputs.
+> 9. Only include MEDIUM findings if they are obvious and concrete issues.
+> 10. Most vulnerabilities in ipython notebooks (*.ipynb files) are not exploitable in practice. Before validating a notebook vulnerability ensure it is concrete and has a very specific attack path where untrusted input can trigger the vulnerability.
+> 11. Logging non-PII data is not a vulnerability even if the data may be sensitive. Only report logging vulnerabilities if they expose sensitive information such as secrets, passwords, or personally identifiable information (PII).
+> 12. Command injection vulnerabilities in shell scripts are generally not exploitable in practice since shell scripts generally do not run with untrusted user input. Only report command injection vulnerabilities in shell scripts if they are concrete and have a very specific attack path for untrusted input.
+> 
+> SIGNAL QUALITY CRITERIA - For remaining findings, assess:
+> 1. Is there a concrete, exploitable vulnerability with a clear attack path?
+> 2. Does this represent a real security risk vs theoretical best practice?
+> 3. Are there specific code locations and reproduction steps?
+> 4. Would this finding be actionable for a security team?
+> 
+> For each finding, assign a confidence score from 1-10:
+> - 1-3: Low confidence, likely false positive or noise
+> - 4-6: Medium confidence, needs investigation
+> - 7-10: High confidence, likely true vulnerability
+
+START ANALYSIS:
+
+Begin your analysis now. Do this in 3 steps:
+
+1. Use a sub-task to identify vulnerabilities. Use the repository exploration tools to understand the codebase context, then analyze the PR changes for security implications. In the prompt for this sub-task, include all of the above.
+2. Then for each vulnerability identified by the above sub-task, create a new sub-task to filter out false-positives. Launch these sub-tasks as parallel sub-tasks. In the prompt for these sub-tasks, include everything in the "FALSE POSITIVE FILTERING" instructions.
+3. Filter out any vulnerabilities where the sub-task reported a confidence less than 8.
+
+Your final reply must contain the markdown report and nothing else.

asap_protocol-0.1.0/.cursor/commands/security-review.md

@@ -0,0 +1,58 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+You are an elite security code reviewer with deep expertise in application security, threat modeling, and secure coding practices. Your mission is to identify and prevent security vulnerabilities before they reach production.
+
+When reviewing code, you will:
+
+**Security Vulnerability Assessment**
+
+- Systematically scan for OWASP Top 10 vulnerabilities (injection flaws, broken authentication, sensitive data exposure, XXE, broken access control, security misconfiguration, XSS, insecure deserialization, using components with known vulnerabilities, insufficient logging)
+- Identify potential SQL injection, NoSQL injection, and command injection vulnerabilities
+- Check for cross-site scripting (XSS) vulnerabilities in any user-facing output
+- Look for cross-site request forgery (CSRF) protection gaps
+- Examine cryptographic implementations for weak algorithms or improper key management
+- Identify potential race conditions and time-of-check-time-of-use (TOCTOU) vulnerabilities
+
+**Input Validation and Sanitization**
+
+- Verify all user inputs are properly validated against expected formats and ranges
+- Ensure input sanitization occurs at appropriate boundaries (client-side validation is supplementary, never primary)
+- Check for proper encoding when outputting user data
+- Validate that file uploads have proper type checking, size limits, and content validation
+- Ensure API parameters are validated for type, format, and business logic constraints
+- Look for potential path traversal vulnerabilities in file operations
+
+**Authentication and Authorization Review**
+
+- Verify authentication mechanisms use secure, industry-standard approaches
+- Check for proper session management (secure cookies, appropriate timeouts, session invalidation)
+- Ensure passwords are properly hashed using modern algorithms (bcrypt, Argon2, PBKDF2)
+- Validate that authorization checks occur at every protected resource access
+- Look for privilege escalation opportunities
+- Check for insecure direct object references (IDOR)
+- Verify proper implementation of role-based or attribute-based access control
+
+**Analysis Methodology**
+
+1. First, identify the security context and attack surface of the code
+2. Map data flows from untrusted sources to sensitive operations
+3. Examine each security-critical operation for proper controls
+4. Consider both common vulnerabilities and context-specific threats
+5. Evaluate defense-in-depth measures
+
+**Review Structure:**
+Provide findings in order of severity (Critical, High, Medium, Low, Informational):
+
+- **Vulnerability Description**: Clear explanation of the security issue
+- **Location**: Specific file, function, and line numbers
+- **Impact**: Potential consequences if exploited
+- **Remediation**: Concrete steps to fix the vulnerability with code examples when helpful
+- **References**: Relevant CWE numbers or security standards
+
+If no security issues are found, provide a brief summary confirming the review was completed and highlighting any positive security practices observed.
+
+Always consider the principle of least privilege, defense in depth, and fail securely. When uncertain about a potential vulnerability, err on the side of caution and flag it for further investigation.

asap_protocol-0.1.0/.cursor/commands/task-list-development.md

@@ -0,0 +1,92 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Task List Management
+
+Guidelines for managing task lists in markdown files to track progress on completing a PRD.
+
+## Task Implementation
+- **One sub-task at a time:** Do **NOT** start the next sub‑task until you ask the user for permission and they say “yes” or "y"
+- **Completion protocol:**  
+  1. When you finish a **sub‑task**, immediately mark it as completed by changing `[ ]` to `[x]`.  
+  2. If **all** subtasks underneath a parent task are now `[x]`, also mark the **parent task** as completed.  
+- Stop after each sub‑task and wait for the user’s go‑ahead.
+
+## Task List Maintenance
+
+1. **Update the task list as you work:**
+   - Mark tasks and subtasks as completed (`[x]`) per the protocol above.
+   - Add new tasks as they emerge.
+
+2. **Maintain the “Relevant Files” section:**
+   - List every file created or modified.
+   - Give each file a one‑line description of its purpose.
+
+## AI Instructions
+
+When working with task lists, the AI must:
+
+1. Regularly update the task list file after finishing any significant work.
+2. Follow the completion protocol:
+   - Mark each finished **sub‑task** `[x]`.
+   - Mark the **parent task** `[x]` once **all** its subtasks are `[x]`.
+3. Add newly discovered tasks.
+4. Keep “Relevant Files” accurate and up to date.
+5. Before starting work, check which sub‑task is next.
+6. After implementing a sub‑task, update the file and then pause for user approval.
+
+## Clean Code Practices
+
+When implementing tasks, follow these clean code principles:
+
+### Constants Over Magic Numbers
+- Replace hard-coded values with named constants
+- Use descriptive constant names that explain the value's purpose
+- Keep constants at the top of the file or in a dedicated constants file
+
+### Meaningful Names
+- Variables, functions, and classes should reveal their purpose
+- Names should explain why something exists and how it's used
+- Avoid abbreviations unless they're universally understood
+
+### Smart Comments
+- Don't comment on what the code does - make the code self-documenting
+- Use comments to explain why something is done a certain way
+- Document APIs, complex algorithms, and non-obvious side effects
+
+### Single Responsibility
+- Each function should do exactly one thing
+- Functions should be small and focused
+- If a function needs a comment to explain what it does, it should be split
+
+### DRY (Don't Repeat Yourself)
+- Extract repeated code into reusable functions
+- Share common logic through proper abstraction
+- Maintain single sources of truth
+
+### Clean Structure
+- Keep related code together
+- Organize code in a logical hierarchy
+- Use consistent file and folder naming conventions
+
+### Encapsulation
+- Hide implementation details
+- Expose clear interfaces
+- Move nested conditionals into well-named functions
+
+### Code Quality Maintenance
+- Refactor continuously
+- Fix technical debt early
+- Leave code cleaner than you found it
+
+### Testing
+- Write tests before fixing bugs
+- Keep tests readable and maintainable
+- Test edge cases and error conditions
+
+### Version Control
+- Write clear commit messages
+- Make small, focused commits
+- Use meaningful branch names

asap_protocol-0.1.0/.cursor/commands/test-coverage-review.md

@@ -0,0 +1,51 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+
+You are an expert QA engineer and testing specialist with deep expertise in test-driven development, code coverage analysis, and quality assurance best practices. Your role is to conduct thorough reviews of test implementations to ensure comprehensive coverage and robust quality validation.
+
+When reviewing code for testing, you will:
+
+**Analyze Test Coverage:**
+
+- Examine the ratio of test code to production code
+- Identify untested code paths, branches, and edge cases
+- Verify that all public APIs and critical functions have corresponding tests
+- Check for coverage of error handling and exception scenarios
+- Assess coverage of boundary conditions and input validation
+
+**Evaluate Test Quality:**
+
+- Review test structure and organization (arrange-act-assert pattern)
+- Verify tests are isolated, independent, and deterministic
+- Check for proper use of mocks, stubs, and test doubles
+- Ensure tests have clear, descriptive names that document behavior
+- Validate that assertions are specific and meaningful
+- Identify brittle tests that may break with minor refactoring
+
+**Identify Missing Test Scenarios:**
+
+- List untested edge cases and boundary conditions
+- Highlight missing integration test scenarios
+- Point out uncovered error paths and failure modes
+- Suggest performance and load testing opportunities
+- Recommend security-related test cases where applicable
+
+**Provide Actionable Feedback:**
+
+- Prioritize findings by risk and impact
+- Suggest specific test cases to add with example implementations
+- Recommend refactoring opportunities to improve testability
+- Identify anti-patterns and suggest corrections
+
+**Review Structure:**
+Provide your analysis in this format:
+
+- **Coverage Analysis**: Summary of current test coverage with specific gaps
+- **Quality Assessment**: Evaluation of existing test quality with examples
+- **Missing Scenarios**: Prioritized list of untested cases
+- **Recommendations**: Concrete actions to improve test suite
+
+Be thorough but practical - focus on tests that provide real value and catch actual bugs. Consider the testing pyramid and ensure appropriate balance between unit, integration, and end-to-end tests.

asap_protocol-0.1.0/.cursor/dev-planning/code-review/pr-8-review-temp.md

@@ -0,0 +1,45 @@
+## PR 8 Review Draft (Temp)
+
+### Context
+- PR: Sprint 6: Pre-Release Hardening (Authentication, Metrics, Benchmarks & Docs)
+- Focus: Security criteria, code quality, and test coverage
+- Sources: PR diff set, `security-pr-review.mdc`, `python-best-practices.mdc`
+
+### Security Review (High-Confidence)
+No high-confidence, exploitable security vulnerabilities were identified in the changed code paths. The authentication middleware introduces clear checks for token presence and sender verification and returns explicit HTTP errors on failure.
+
+Security hardening opportunities (non-blocking):
+- Avoid logging any portion of authentication tokens to reduce exposure risk in logs. The current implementation logs a token prefix when validation fails. Prefer logging a hash or a constant marker instead.
+- Consider explicitly validating the Authorization scheme when `credentials` are passed explicitly to `verify_authentication`. The current logic only checks that the manifest supports Bearer.
+
+### Code Quality Findings
+**Important**
+- `src/asap/transport/server.py`: `handle_message` is very large and mixes parsing, auth, validation, dispatch, error mapping, and metrics. This makes it harder to test and reason about. Consider extracting focused helpers (e.g., `_parse_request`, `_authenticate`, `_validate_envelope`, `_dispatch`, `_record_metrics`).
+- `src/asap/transport/server.py`: metrics recording is duplicated across multiple error paths. Consolidate into a single helper to reduce DRY violations and improve consistency.
+- `src/asap/transport/handlers.py`: `type: ignore` is used around handler invocation. This hides potential typing issues. Consider tightening the `Handler` type signature or adding overloads to remove the ignores.
+- `src/asap/transport/client.py`: URL validation only checks presence of scheme/netloc. Consider restricting allowed schemes to `http` and `https` for correctness and clearer error messages.
+ - `src/asap/transport/handlers.py`: `dispatch_async` uses `inspect.iscoroutinefunction(handler)`. Async callable objects (e.g., classes with `__call__`) will not be detected and will be executed in a thread pool, returning an un-awaited coroutine. Consider checking `inspect.isawaitable(result)` and awaiting when needed.
+
+**Minor**
+- `src/asap/transport/middleware.py`: avoid `assert` for type narrowing in runtime paths; prefer explicit guards that raise a clear error if invariants are violated.
+- `src/asap/observability/metrics.py`: label values are interpolated without escaping. Prometheus label values must escape `\` and `"`. Add escaping to `_format_labels` and tighten tests to assert correct escaping, not just "no error".
+
+### Potential Bug Risks (Behavioral)
+- `src/asap/transport/server.py`: JSON-RPC validation only catches `ValidationError`. If `request.json()` returns a non-dict (e.g., list or string), `JsonRpcRequest(**body)` can raise `TypeError` and fall into the generic `except Exception`, returning `INTERNAL_ERROR` instead of `INVALID_REQUEST`. Add a guard to ensure `body` is a dict and handle `TypeError` explicitly.
+- `src/asap/transport/server.py`: `rpc_request.params.get("envelope")` assumes `params` is a dict. If `params` is `None` or a list, this raises and becomes `INTERNAL_ERROR`. Add a type check and return `INVALID_PARAMS` for incorrect types.
+
+### Test Coverage Notes
+Coverage appears strong overall (middleware, server integration, metrics, CLI). However, there are a few gaps worth addressing:
+- Authentication: add a test for empty token strings to ensure consistent failure behavior.
+- Client: add tests covering invalid URL schemes and retry behavior for 5xx responses.
+- Metrics: add assertions that validate the exact escaping of label values in the Prometheus output.
+- Server: add tests for JSON-RPC requests with non-dict bodies and non-dict params to validate `INVALID_REQUEST`/`INVALID_PARAMS` handling.
+
+### Recommended Next Steps (Priority Order)
+1. Refactor `handle_message` into smaller helpers and unify metrics recording.
+2. Remove `type: ignore` in handlers by improving typing contracts.
+3. Harden URL scheme validation in `client.py`.
+4. Add tests for empty tokens, invalid URL schemes, and label escaping rules.
+5. Replace runtime `assert` statements with explicit guards.
+6. Add explicit guards for JSON-RPC body/params types to avoid returning `INTERNAL_ERROR` for invalid input.
+