forge-orkes 0.3.7 → 0.3.9

package/template/.claude/skills/auditing/SKILL.md

@@ -1,314 +0,0 @@
----
-name: auditing
-description: "Use after verifying passes to assess overall application health before milestone completion. Runs security audit (10 categories) and architecture audit (scaling, maintainability, code health). This is the pre-release gate — it answers 'is this codebase healthy enough to ship?'"
----
-
-# Auditing: Health Audit Before Milestone Completion
-
-You are the pre-release gate. After `verifying` confirms the work delivers what was promised, you assess whether the codebase is healthy enough to ship. Two parallel audits — security and architecture — produce a structured health report that determines whether the milestone can complete.
-
-## When to Trigger
-
-- **Automatically** after `verifying` returns a PASSED verdict (Standard and Full tiers)
-- **On-demand** at any time via user request
-
-## Process Overview
-
-1. Read project context (`.forge/project.yml`) to determine tech stack
-2. Scope the audit — glob all source files, summarize what will be scanned
-3. Spawn two parallel subagents: Security Audit + Architecture Audit
-4. Collect results, score per-category, determine overall status
-5. Write health report to `.forge/audits/milestone-{id}-health-report.md`
-6. Route based on results: healthy → complete, issues → user decides
-
-## Step 1: Read Context
-
-```
-Read: .forge/project.yml → tech stack, framework, database, dependencies
-Read: .forge/state/milestone-{id}.yml → milestone ID and name
-Read: .forge/constitution.md → active architectural gates (if exists)
-```
-
-Determine which security categories apply based on the tech stack. For example:
-- No database → SQL/NoSQL Injection is N/A
-- No frontend → XSS Prevention is N/A
-- No CI/CD config → Pipeline Security is N/A
-
-## Step 2: Scope the Audit
-
-```
-Glob: src/**/*.{ts,tsx,js,jsx,py,go,rs,java} (adapt to project language)
-Glob: **/*.env*, **/docker-compose*, **/.github/workflows/*
-Glob: **/next.config*, **/vite.config*, **/webpack.config*
-```
-
-Present scope summary to user:
-*"Health audit scope: {N} source files, {N} config files. Scanning for security vulnerabilities (10 categories) and architectural health (4 dimensions). This will take a moment."*
-
-Build explicit file lists for each subagent — pass file paths, not globs, so nothing is missed.
-
-## Step 3: Spawn Parallel Audits
-
-Spawn both audits as fresh-context subagents. Each receives:
-- The explicit file list for their scope
-- The tech stack from `project.yml`
-- Their specific audit instructions (below)
-
-### Part 1: Security Audit (subagent)
-
-Spawn a security auditor agent with a fresh context window.
-
-**10 Security Categories:**
-
-| # | Category | What It Checks |
-|---|----------|---------------|
-| 1 | Authentication & Authorization | Every endpoint has auth middleware; role checks before data access |
-| 2 | Data Scoping / Tenant Isolation | Queries scoped to correct user/tenant; no cross-tenant data leaks |
-| 3 | Input Validation | Request bodies/params validated before use in queries or logic |
-| 4 | Error Information Leakage | No stack traces, DB schemas, or internal details in API responses |
-| 5 | XSS Prevention | No unsanitized user content injected into DOM |
-| 6 | SQL/NoSQL Injection | All queries use parameterized placeholders, no string interpolation |
-| 7 | Secrets Management | No hardcoded keys/tokens; `.env` in `.gitignore`; `process.env` usage |
-| 8 | CORS Policy | No wildcard `*` origins in production; appropriate method restrictions |
-| 9 | HTTP Security Headers | CSP, X-Frame-Options, HSTS, X-Content-Type-Options, Referrer-Policy |
-| 10 | CI/CD Pipeline Security | Secrets via secrets context, not hardcoded in workflow files |
-
-**Agent behavior rules:**
-- Read every file in the provided list. No sampling or skipping.
-- Every finding must have: file path, line number, what's wrong, severity, remediation.
-- Understand context before flagging — read surrounding code, check for middleware, wrappers, and higher-order protections.
-- Document intentionally public endpoints; don't flag them as vulnerabilities.
-- Severity is firm: `critical` = exploitable vulnerability, `warning` = defense-in-depth gap, `info` = observation.
-- Prefer false negatives over false positives — only flag what you're confident about.
-- Categories that don't apply to this project's stack → mark as N/A with brief explanation.
-
-**Project adaptation:** Adapt checks to the detected stack:
-- Express vs Next.js vs Fastify endpoint patterns
-- PostgreSQL vs MongoDB vs SQLite query patterns
-- GitHub Actions vs GitLab CI vs other CI systems
-- React vs Vue vs Svelte frontend patterns
-
-**Output format** (return to orchestrator):
-
-```yaml
-security_audit:
-  files_scanned: N
-  categories:
-    - id: 1
-      name: "Authentication & Authorization"
-      status: passed | warning | critical | na
-      findings:
-        - file: "src/api/users.ts"
-          line: 42
-          severity: critical | warning | info
-          issue: "Description of what's wrong"
-          remediation: "How to fix it"
-      notes: "Optional context about intentional decisions"
-```
-
-### Part 2: Architecture Audit (subagent)
-
-Spawn an architecture auditor agent with a fresh context window.
-
-**4 Architecture Dimensions:**
-
-| Dimension | What It Checks |
-|-----------|---------------|
-| **Scalability** | Synchronous blocking calls, missing pagination, unbounded queries, N+1 query patterns, missing caching opportunities, single points of failure, hardcoded limits |
-| **Maintainability** | Code complexity hotspots (files >300 lines, deeply nested logic >4 levels, god components/classes), circular dependencies, duplicated logic that warrants abstraction |
-| **Code Health** | Dead code / unused exports, TODO/FIXME inventory with age, test coverage gaps (untested critical paths), stale/vulnerable dependencies |
-| **Structural Quality** | Separation of concerns violations (business logic in UI layer), inconsistent patterns across similar features, missing error boundaries, API contract consistency |
-
-**Agent behavior rules:**
-- Check actual code, not theoretical concerns.
-- Every finding references specific files with evidence.
-- Severity: `critical` = architectural debt that will cause production issues or block future work, `warning` = quality concern worth addressing, `info` = improvement opportunity.
-- Respect existing ADRs in `.forge/decisions/` — don't flag intentional architectural choices as issues.
-- Respect constitutional articles in `.forge/constitution.md` — if the constitution permits a pattern, don't flag it.
-
-**Output format** (return to orchestrator):
-
-```yaml
-architecture_audit:
-  files_scanned: N
-  dimensions:
-    - name: "Scalability"
-      status: passed | warning | critical
-      findings:
-        - file: "src/api/products.ts"
-          line: 87
-          severity: critical | warning | info
-          issue: "Unbounded query with no pagination"
-          remediation: "Add limit/offset parameters"
-    - name: "Maintainability"
-      status: passed | warning | critical
-      findings: []
-    - name: "Code Health"
-      status: passed | warning | critical
-      findings: []
-    - name: "Structural Quality"
-      status: passed | warning | critical
-      findings: []
-```
-
-## Step 4: Score Results
-
-After both subagents return, compute scores.
-
-**Per-category scoring:**
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | No issues found |
-| `warning` | Non-critical issues (info-level also maps here) |
-| `critical` | Real vulnerabilities or architectural blockers |
-| `na` | Category doesn't apply to this project |
-
-**Overall status:**
-
-| Overall | Condition |
-|---------|-----------|
-| `passed` | ALL categories and dimensions passed or N/A |
-| `warnings_only` | One or more warnings, zero critical |
-| `issues_found` | One or more critical findings |
-
-## Step 5: Write Health Report
-
-Create `.forge/audits/` directory if needed. Write to `.forge/audits/milestone-{id}-health-report.md`.
-
-**YAML frontmatter:**
-
-```yaml
----
-milestone_id: {id}
-milestone_name: "{name}"
-audited: "{ISO 8601 timestamp}"
-status: passed | warnings_only | issues_found
-security:
-  status: passed | warnings_only | issues_found
-  categories_passed: N
-  categories_warning: N
-  categories_critical: N
-  categories_na: N
-architecture:
-  status: passed | warnings_only | issues_found
-  scalability: passed | warning | critical
-  maintainability: passed | warning | critical
-  code_health: passed | warning | critical
-  structural_quality: passed | warning | critical
-total_files_scanned: N
----
-```
-
-**Body structure:**
-
-```markdown
-# Health Audit Report: {milestone name}
-
-## Executive Summary
-{1-3 sentences: overall health assessment, key findings, recommendation}
-
-## Security Findings
-
-### Category 1: Authentication & Authorization — {STATUS}
-| File | Line | Severity | Issue | Remediation |
-|------|------|----------|-------|-------------|
-| ... | ... | ... | ... | ... |
-
-{Repeat for each category. N/A categories get a single line: "N/A — {reason}"}
-
-## Architecture Findings
-
-### Scalability — {STATUS}
-| File | Line | Severity | Issue | Remediation |
-|------|------|----------|-------|-------------|
-| ... | ... | ... | ... | ... |
-
-{Repeat for each dimension}
-
-## Public Endpoints
-{List of intentionally public endpoints documented during security audit}
-
-## Files Scanned
-{Count and list of all files scanned across both audits}
-```
-
-**Health trend tracking:** If a previous audit exists for an earlier milestone (check `.forge/audits/` for prior reports), compare results and note improvements or regressions in the executive summary.
-
-## Step 6: Route Based on Results
-
-### HEALTHY (all passed)
-
-Update `.forge/state/milestone-{id}.yml`:
-- Set `current.status` to `refactoring`
-
-Present to user:
-*"Health audit passed. No security vulnerabilities or architectural concerns found. Moving to refactoring review."*
-
-→ Route to `refactoring` skill.
-
-### NEEDS ATTENTION (critical issues found)
-
-Do NOT mark milestone complete. Present to user:
-
-*"Health audit found critical issues that should be addressed before shipping:"*
-
-Inline the top 3 findings per critical category so the user sees them immediately (don't make them open the report).
-
-Then offer choices:
-
-*"Options:"*
-- **A. Fix critical issues** — return to `planning` in fix mode with findings as requirements
-- **B. Accept risk and continue** — document accepted risks in report, proceed to refactoring review
-
-If user chooses A:
-- Create fix requirements from critical findings
-- Route to `planning` skill in fix mode
-- After fix execution, re-run `auditing` (not full `verifying` — just the audit)
-
-If user chooses B:
-- Append "Accepted Risks" section to the health report with user's acknowledgment
-- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
-- → Route to `refactoring` skill.
-
-### ACCEPTABLE WITH CAVEATS (warnings only)
-
-Present to user:
-
-*"Health audit passed with warnings — no critical issues, but {N} items worth noting. See the full report at `.forge/audits/milestone-{id}-health-report.md`."*
-
-Then offer choices:
-- **A. Continue to refactoring review** — accept warnings as known items
-- **B. Fix warnings** — address before continuing
-
-If user chooses A:
-- Document accepted warnings in report
-- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
-- → Route to `refactoring` skill.
-
-If user chooses B:
-- Create fix requirements from warning findings
-- Route to `planning` in fix mode
-- After fix execution, re-run `auditing`
-
-## Gate Type: Soft Gate
-
-This is a soft gate — critical issues strongly recommend fixing before completion, but the user can accept risk and proceed. Rationale:
-- Some issues may be acceptable known risks for the deployment context
-- Some findings may be false positives despite the conservative flagging approach
-- Non-production or internal tools may have different risk tolerances
-- The user always has final authority over ship decisions
-
-The report documents the decision either way, creating an audit trail.
-
-## Phase Handoff
-
-After auditing routes to refactoring (all three paths: HEALTHY, accepted risk, accepted warnings):
-
-1. **Verify persistence** — Confirm health report is written to `.forge/audits/milestone-{id}-health-report.md`
-2. **Update state** — Set `current.status` to `refactoring` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
-
-*"Health audit complete. Report written to `.forge/audits/`. I recommend clearing context (`/clear`) before the refactoring review — the refactoring scanner spawns a fresh agent with the git diff and health report, so a clean context ensures accurate scanning.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*

package/template/.claude/skills/refactoring/SKILL.md

@@ -1,168 +0,0 @@
----
-name: refactoring
-description: "Review code built during a milestone for refactoring opportunities. Runs after auditing passes. Produces a structured backlog of improvements the user can work through via quick-tasking. Soft gate — review items, add to backlog, complete milestone."
----
-
-# Refactoring: Post-Milestone Code Review for Improvement Opportunities
-
-You review the code built during a milestone and catalog opportunities for improvement. This is not about correctness (that's `verifying`) or health (that's `auditing`) — it's about identifying code that works but could be cleaner, simpler, or more consistent.
-
-## When to Trigger
-
-- **Automatically** after `auditing` completes (all three paths: HEALTHY, NEEDS ATTENTION after fix, ACCEPTABLE WITH CAVEATS after accept)
-- **On-demand** at any time via user request
-
-## Step 1: Read Context
-
-```
-Read: .forge/project.yml → tech stack, conventions
-Read: .forge/state/milestone-{id}.yml → milestone ID, name, phases completed
-Read: .forge/audits/milestone-{id}-health-report.md → health findings (avoid overlap)
-Read: .forge/refactor-backlog.yml → existing backlog items (if any)
-Read: .forge/constitution.md → active architectural gates (if exists)
-```
-
-Determine the milestone's starting point for the git diff:
-- Check git log for the commit tagged or noted as the milestone start
-- If unavailable, use the first commit after the previous milestone's completion date
-- Fallback: ask the user for the starting commit or branch
-
-## Step 2: Scan Milestone Code
-
-Spawn a fresh agent with isolated context. Pass it:
-- The explicit list of files changed during the milestone (from `git diff --name-only {start}..HEAD`)
-- The tech stack from `project.yml`
-- The health report findings (so it doesn't duplicate auditing's work)
-- The constitution (so it respects intentional decisions)
-
-**The agent scans for 6 categories:**
-
-| # | Category | What to Look For |
-|---|----------|-----------------|
-| 1 | **Duplication** | Similar logic in 2+ places that could be extracted into a shared function, hook, or utility |
-| 2 | **Complexity hotspots** | Functions >50 lines, nesting >3 levels deep, high cyclomatic complexity, overly long files |
-| 3 | **Naming & clarity** | Unclear variable/function names, misleading abstractions, functions that do more than their name suggests |
-| 4 | **Pattern inconsistency** | Same thing done differently across the milestone's files (e.g., error handling, data fetching, state management) |
-| 5 | **Dead code** | Unused functions, unreachable branches, commented-out code left behind, unused imports |
-| 6 | **Abstraction issues** | Over-engineered helpers used once, repeated inline code that warrants extraction, premature or missing abstractions |
-
-**Agent behavior rules:**
-- Read every file in the diff. No sampling.
-- Every finding must reference a specific file and line range.
-- Understand context — don't flag intentional patterns documented in the constitution.
-- Don't duplicate findings already in the health report from auditing.
-- Estimate effort for each item: `quick` (< 30 min, under 50 lines) or `standard` (needs planning).
-- Suggest a concrete approach for each finding, not just "refactor this."
-- Prefer fewer high-quality findings over many low-signal ones.
-
-**Output format** (return to orchestrator):
-
-```yaml
-findings:
-  - category: duplication
-    file: "src/api/users.ts"
-    lines: "42-67"
-    description: "Duplicate validation logic — same email check in createUser and updateUser"
-    effort: quick
-    suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
-  - category: complexity
-    file: "src/components/Dashboard.tsx"
-    lines: "120-245"
-    description: "Dashboard render function is 125 lines with 4 levels of nesting"
-    effort: standard
-    suggested_approach: "Extract stat cards, chart section, and filter bar into subcomponents"
-```
-
-## Step 3: Present Findings to User
-
-Group findings by category. Show each with:
-- File and line range
-- What the issue is
-- Estimated effort
-- Suggested approach
-
-Present top findings (max 10 initially). If there are more, mention the count.
-
-*"I found {N} refactoring opportunities in the code built during this milestone:"*
-
-Then for each category with findings:
-
-*"**Duplication** ({N} items):*
-*1. `src/api/users.ts:42-67` — Duplicate email validation in createUser and updateUser. Quick fix: extract shared helper. [Accept / Dismiss]*
-*2. ...*"
-
-## Step 4: User Triage
-
-The user can respond with:
-- **Accept** (individual item) → add to backlog
-- **Dismiss** (individual item) → skip, not a real issue or intentional
-- **Accept all** → bulk add all remaining items to backlog
-- **Dismiss all** → skip everything, no backlog items added
-
-For dismissed items, optionally ask for a brief reason (helps calibrate future scans).
-
-## Step 5: Write Backlog
-
-Read existing `.forge/refactor-backlog.yml` (if any). Determine the next item ID by incrementing from the highest existing ID.
-
-Append accepted items to `.forge/refactor-backlog.yml`:
-
-```yaml
-items:
-  - id: R001
-    milestone: 1
-    category: duplication
-    file: "src/api/users.ts"
-    lines: "42-67"
-    description: "Duplicate validation logic — same email check in createUser and updateUser"
-    effort: quick
-    suggested_approach: "Extract shared validateEmail() helper"
-    status: pending
-    added: "2026-03-18"
-    completed: null
-```
-
-If the file doesn't exist yet, create it from the template at `.forge/templates/refactor-backlog.yml`.
-
-Present summary:
-*"Added {N} items to the refactor backlog. {M} dismissed. You can work these anytime — pending items with `effort: quick` will show up as available Quick tasks when you start a session."*
-
-## Step 6: Route
-
-Update `.forge/state/milestone-{id}.yml`:
-- Set `current.status` to `complete`
-
-Update `.forge/state/index.yml`:
-- Set milestone status to `complete`
-- Update `last_updated` timestamp
-
-Present to user:
-*"Milestone [{name}] is complete. {N} refactoring items are in the backlog for whenever you want to tackle them."*
-
-If Beads is installed, run `bd complete` to update the dependency graph.
-
-## Gate Type: Soft Gate
-
-This is a soft gate — it presents opportunities but never blocks milestone completion. Rationale:
-- Refactoring is improvement, not correctness. The code already works (verified) and is healthy (audited).
-- Users should review opportunities but aren't forced to act on them immediately.
-- Backlog items persist across sessions and can be worked whenever it makes sense.
-- Some items may become irrelevant as the codebase evolves — that's fine.
-
-## Backlog Lifecycle
-
-Backlog items follow this lifecycle:
-
-```
-pending → in_progress → done
-pending → dismissed (during triage or later review)
-```
-
-Items with `effort: quick` can be picked up directly via `quick-tasking`.
-Items with `effort: standard` should go through the Standard tier flow.
-
-When working a backlog item:
-1. `forge` surfaces it as an available task
-2. User selects it
-3. Route to `quick-tasking` or Standard tier based on effort
-4. On completion, update the item's `status` to `done` and set `completed` date