From 1db482b958173de3da54475c9a2029107635c9fe Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Tue, 25 Aug 2026 11:34:41 -0700 Subject: [PATCH] docs(tasks): extract and establish audit-1 and audit-2 protocol templates --- tasks/audit-1.md | 65 +++++++++++++++++++++++++++++++++++++++++++++ tasks/audit-2.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++ tasks/path.md | 57 ++++++++++++++++++++++++--------------- 3 files changed, 170 insertions(+), 21 deletions(-) create mode 100644 tasks/audit-1.md create mode 100644 tasks/audit-2.md diff --git a/tasks/audit-1.md b/tasks/audit-1.md new file mode 100644 index 0000000..4a92d0d --- /dev/null +++ b/tasks/audit-1.md @@ -0,0 +1,65 @@ +# Task Plan & Specification Audit Protocol (`tasks/audit-1.md`) + +This protocol defines the standard for auditing, grading, and refining new task +files in `tasks/new/` before implementation begins. + +--- + +## 1. Direct Execution Protocol (When Running the Audit Yourself) + +When commanded to **"Run Audit-1 on `[TASK_FILE]`"**: + +1. **Remain Strictly Read-Only:** Do not modify any codebase files or task files + during the audit. +2. **Examine the Codebase:** Inspect the current architecture to verify if the + task's assumptions, dependencies, and target files are accurate. +3. **Score against the 5-Point Plan Rubric:** + - **Criterion 1 (Standards Compliance):** Adheres to `tasks/GUIDELINES.md` + naming conventions (`YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`) and + contains the mandatory `# TASK METADATA` header. + - **Criterion 2 (Architectural Safety):** Identifies real technical risks + (event loop blocks, memory leaks, cache staleness, monolithic sprawl, + zero-trust bypasses) with mitigations. + - **Criterion 3 (Purity & Simplicity):** Evaluates native/simpler + alternatives and avoids dependency/code bloat. + - **Criterion 4 (Implementation Precision):** Target files, functions, SQL + schemas, and error boundaries are unambiguously specified. + - **Criterion 5 (Testing Rigor):** Includes unit/integration test plans + covering happy paths, edge cases, and 401/403 security gates. +4. **Output the Standard Audit Report:** + - **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade] + - **Verdict:** [APPROVED / NEEDS REVISION / REJECTED] + - **Strengths & Plan Alignment:** What the plan gets right. + - **Identified Gaps & Failure Risks:** Missing edge cases, risks, or + regressions. + - **Concrete Suggested Revisions:** Exact text, parameters, or steps to + add/change in the task file. + +--- + +## 2. Dispatch Template (When Preparing a Prompt for Jules or External Agents) + +When commanded to **"Prepare an Audit-1 prompt for Jules"**, fill in and provide +the following block: + +```text +**Role:** Act as a Principal Systems Architect and Task Quality Critic. Do not modify the codebase or execute code during this session. Your sole deliverable is a structured task critique report. + +**The Scope:** Review the newly generated task file in `[tasks/new/TASK_FILENAME.md]` against our master architectural guidelines (`AGENTS.md`, `docs/`, `tasks/GUIDELINES.md`). + +**Your Task:** +Critically evaluate the proposed task plan against the 5-point quality rubric in `tasks/audit-1.md`: +1. Metadata & Standards Compliance +2. Architectural Alignment & Safety +3. Purity & Simplicity (Avoiding bloat) +4. Implementation Precision & State Machine +5. Testing & Quality Gate Rigor + +**Deliverable:** +Provide a structured critique report with: +- **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade] +- **Verdict:** [APPROVED / NEEDS REVISION / REJECTED] +- **Strengths & Plan Alignment:** Key architectural insights captured in the plan. +- **Identified Gaps & Potential Risks:** Missing edge cases, unaddressed failure modes, or UX/architectural oversights. +- **Concrete Suggested Revisions:** Exact adjustments, additions, or rewordings to incorporate into the task file before implementation starts. +``` diff --git a/tasks/audit-2.md b/tasks/audit-2.md new file mode 100644 index 0000000..26c50f2 --- /dev/null +++ b/tasks/audit-2.md @@ -0,0 +1,69 @@ +# Implementation & Code Quality Audit Protocol (`tasks/audit-2.md`) + +This protocol defines the standard for auditing code changes, PR branches, or +completed tasks before merging or releasing. + +--- + +## 1. Direct Execution Protocol (When Running the Audit Yourself) + +When commanded to **"Run Audit-2 on `[BRANCH / TASK / FILES]`"**: + +1. **Remain Strictly Read-Only:** Do not modify code, commit changes, or push to + remotes during the audit. +2. **Inspect Actual Code Changes:** Compare the modified files against the + original task specification and `AGENTS.md`. +3. **Score against the 5-Point Implementation Rubric:** + - **Criterion 1 (Spec & Scope Fidelity):** Built exactly what was requested + without omitting core features, introducing rogue edits, or degrading + existing UX. + - **Criterion 2 (Zero-Trust Security & Boundary Safety):** Scope guards, + session isolation, and error boundaries are verified. Zero privilege + escalation risks. + - **Criterion 3 (Modularity & Clean Architecture):** Clean separation of + concerns without contributing to file bloat, monolithic sprawl, or circular + imports. + - **Criterion 4 (Quality Gates & Test Evidence):** `deno fmt`, + `deno task lint`, `deno task check`, and `deno test --allow-all` pass with + 0 errors/warnings. Comprehensive test coverage for happy and failure paths. + - **Criterion 5 (Runtime & Client-Side Integrity):** For UI changes, zero + runtime JS parsing/syntax errors (validated via `ui/ui_scripts.test.ts`), + accessible layout, and consistent styling tokens. +4. **Output the Standard Code Audit Report:** + - **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade] + - **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED] + - **Successes & Verified Achievements:** Verified working features with + evidence. + - **Deficiencies, Regressions & Failure Risks:** Bugs, unhandled errors, UX + regressions, or security gaps found. + - **Actionable Remediation Suggestions:** Specific, prioritized code changes + needed before release. + +--- + +## 2. Dispatch Template (When Preparing a Prompt for Jules or External Agents) + +When commanded to **"Prepare an Audit-2 prompt for Jules"**, fill in and provide +the following block: + +```text +**Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report. + +**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`]. + +**Your Task:** +Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`: +1. Specification & Scope Fidelity +2. Zero-Trust Security & Boundary Safety +3. Modularity & Clean Architecture +4. Quality Gates & Test Evidence +5. Runtime & Client-Side Integrity + +**Deliverable:** +Provide a structured code audit report with: +- **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade] +- **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED] +- **Successes & Verified Achievements:** Exact functionality verified and working as expected. +- **Deficiencies, Regressions & Failure Risks:** Technical bugs, unhandled errors, UX regressions, or security gaps found. +- **Actionable Remediation Suggestions:** Specific, prioritized code fixes or refactoring steps needed before final approval. +``` diff --git a/tasks/path.md b/tasks/path.md index 7d444c9..c778421 100644 --- a/tasks/path.md +++ b/tasks/path.md @@ -53,48 +53,63 @@ in an existing task file._ --- -## 3. Pre-PR Quality & Security Audit Template (Auditor) +## 3. Implementation & Code Quality Audit Template (`tasks/audit-2.md`) -_Use this template to instruct an agent to perform an exhaustive pre-merge -audit._ +_Use this template to perform an exhaustive post-implementation audit on code +changes, PR branches, or completed tasks before merging or deploying. See +complete protocol in +[`tasks/audit-2.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-2.md)._ ```text -**Role:** Act as a Senior Security & Quality Assurance Auditor. +**Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report. -**The Scope:** [List recent changes, PR branch, or target components to audit.] +**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`]. **Your Task:** -1. Inspect code changes against architectural boundaries. -2. Verify zero regression in authentication, session management, or RBAC grants. -3. Confirm all unit and integration tests pass with 0 lint warnings and 0 typecheck errors. -4. Document findings and generate an audit report if any vulnerabilities or performance bottlenecks are detected. +Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`: +1. Specification & Scope Fidelity +2. Zero-Trust Security & Boundary Safety +3. Modularity & Clean Architecture +4. Quality Gates & Test Evidence +5. Runtime & Client-Side Integrity + +**Deliverable:** +Provide a structured code audit report with: +- **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade] +- **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED] +- **Successes & Verified Achievements:** Exact functionality verified and working as expected. +- **Deficiencies, Regressions & Failure Risks:** Technical bugs, unhandled errors, UX regressions, or security gaps found. +- **Actionable Remediation Suggestions:** Specific, prioritized code fixes or refactoring steps needed before final approval. ``` --- -## 4. Task Plan Review & Critique Template (Architect / Critic) +## 4. Task Plan Review & Critique Template (`tasks/audit-1.md`) _Use this template to critically audit, score, and refine new task files in -`tasks/new/` before approving them for implementation._ +`tasks/new/` before approving them for implementation. See complete protocol in +[`tasks/audit-1.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-1.md)._ ```text -**Role:** Act as a Principal Systems Architect and Task Quality Critic. +**Role:** Act as a Principal Systems Architect and Task Quality Critic. Do not modify the codebase or execute code during this session. Your sole deliverable is a structured task critique report. -**The Scope:** Review the newly generated task file in `tasks/new/[TASK_FILENAME].md`. +**The Scope:** Review the newly generated task file in `[tasks/new/TASK_FILENAME.md]` against our master architectural guidelines (`AGENTS.md`, `docs/`, `tasks/GUIDELINES.md`). **Your Task:** -Critically evaluate the proposed task plan against the following 5-point quality rubric: -1. **Metadata & Standards Compliance:** Does the file strictly adhere to `tasks/GUIDELINES.md` naming conventions and include the exact `# TASK METADATA` header? -2. **Architectural Boundary Safety:** Does the plan identify genuine technical risks (e.g., event loop blocking, memory leaks, cache staleness, zero-trust perimeter bypasses) and provide concrete mitigations? -3. **Alternatives & Zero-Dependency Purity:** Did the author evaluate simpler or more native alternatives and justify why the proposed design avoids dependency bloat? -4. **Implementation Precision:** Are target functions, data structures, SQL migrations, FFI symbols, and error boundaries defined with crystal clarity? -5. **Testing & Quality Gate Rigor:** Does the proposed implementation include comprehensive unit/integration test specifications covering both happy-path and failure modes? +Critically evaluate the proposed task plan against the 5-point quality rubric in `tasks/audit-1.md`: +1. Metadata & Standards Compliance +2. Architectural Alignment & Safety +3. Purity & Simplicity (Avoiding bloat) +4. Implementation Precision & State Machine +5. Testing & Quality Gate Rigor **Deliverable:** Provide a structured critique report with: +- **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade] - **Verdict:** [APPROVED / NEEDS REVISION / REJECTED] -- **Strengths:** Key architectural insights captured by the author. -- **Identified Gaps & Refinements:** Concrete adjustments to incorporate into the task file before implementation starts. +- **Strengths & Plan Alignment:** Key architectural insights captured in the plan. +- **Identified Gaps & Potential Risks:** Missing edge cases, unaddressed failure modes, or UX/architectural oversights. +- **Concrete Suggested Revisions:** Exact adjustments, additions, or rewordings to incorporate into the task file before implementation starts. ``` ---