forge-orkes 0.3.8 → 0.3.10

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

@@ -0,0 +1,406 @@
+---
+name: reviewing
+description: "Post-verification health gate. Runs security audit (10 categories), architecture audit (4 dimensions), and refactoring scan (6 categories) in parallel. Determines if the milestone can ship and catalogs improvement opportunities."
+---
+
+# Reviewing: Health Audit + Refactoring Review
+
+The pre-completion gate. After `verifying` confirms deliverables, assess codebase health and catalog improvements. Three parallel scans produce a structured report that gates milestone completion.
+
+## Triggers
+
+- **Auto:** after `verifying` returns PASSED (Standard/Full tiers)
+- **Manual:** on user request
+
+## Process
+
+1. Read project context from `.forge/project.yml`
+2. Scope the review — glob source files, determine milestone diff
+3. Spawn three parallel subagents: Security + Architecture + Refactoring
+4. Collect results, score per-category, determine overall status
+5. Write health report to `.forge/audits/milestone-{id}-health-report.md`
+6. Write accepted refactoring items to `.forge/refactor-backlog.yml`
+7. Route: healthy → complete, critical → 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)
+Read: .forge/refactor-backlog.yml → existing backlog items (if any)
+```
+
+Skip inapplicable security categories based on tech stack:
+- No database → SQL/NoSQL Injection N/A
+- No frontend → XSS Prevention N/A
+- No CI/CD config → Pipeline Security N/A
+
+Determine the milestone's git diff starting point:
+- Check git log for the milestone start commit
+- Fallback: first commit after previous milestone's completion date
+- Last resort: ask the user
+
+## Step 2: Scope the Review
+
+```
+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*
+```
+
+Get diff file list for refactoring scan:
+```
+git diff --name-only {milestone_start}..HEAD
+```
+
+Present scope summary:
+*"Review scope: {N} source files, {N} config files, {N} changed files. Scanning security (10), architecture (4), refactoring (6)."*
+
+Build explicit file lists for each subagent — pass paths, not globs.
+
+## Step 3: Spawn Parallel Scans
+
+Spawn all three as fresh-context subagents. Each receives: explicit file list, tech stack from `project.yml`, instructions below.
+
+### Part 1: Security Audit (subagent)
+
+**10 Security Categories:**
+
+| # | Category | 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 leaks |
+| 3 | Input Validation | Request bodies/params validated before use |
+| 4 | Error Information Leakage | No stack traces, DB schemas, or internals in API responses |
+| 5 | XSS Prevention | No unsanitized user content injected into DOM |
+| 6 | SQL/NoSQL Injection | All queries parameterized, 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 workflows |
+
+**Rules:**
+- Read every file. No sampling.
+- Every finding needs: file path, line number, issue, severity, remediation.
+- Check surrounding code for middleware/wrappers before flagging.
+- Document intentionally public endpoints — don't flag them.
+- Severity: `critical` = exploitable vulnerability, `warning` = defense-in-depth gap, `info` = observation.
+- Prefer false negatives over false positives.
+- Inapplicable categories → N/A with brief reason.
+
+**Adapt checks to detected stack:** Express/Next.js/Fastify endpoints, PostgreSQL/MongoDB/SQLite queries, GitHub Actions/GitLab CI, React/Vue/Svelte frontends.
+
+**Output format:**
+
+```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)
+
+**4 Dimensions:**
+
+| Dimension | Checks |
+|-----------|--------|
+| **Scalability** | Synchronous blocking, missing pagination, unbounded queries, N+1 patterns, missing caching, single points of failure, hardcoded limits |
+| **Maintainability** | Files >300 lines, nesting >4 levels, god components/classes, circular deps, duplicated logic warranting abstraction |
+| **Code Health** | Dead code/unused exports, TODO/FIXME inventory with age, untested critical paths, stale/vulnerable deps |
+| **Structural Quality** | Business logic in UI layer, inconsistent patterns across features, missing error boundaries, API contract inconsistency |
+
+**Rules:**
+- Check actual code, not theoretical concerns.
+- Every finding references specific files with evidence.
+- Severity: `critical` = debt causing production issues or blocking future work, `warning` = quality concern, `info` = improvement opportunity.
+- Respect existing ADRs in `.forge/decisions/` and constitutional articles — don't flag intentional choices.
+
+**Output format:**
+
+```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: []
+```
+
+### Part 3: Refactoring Scan (subagent)
+
+Pass only files changed during the milestone (from git diff).
+
+**6 Categories:**
+
+| # | Category | Look For |
+|---|----------|----------|
+| 1 | **Duplication** | Similar logic in 2+ places extractable into shared function/hook/utility |
+| 2 | **Complexity hotspots** | Functions >50 lines, nesting >3 levels, high cyclomatic complexity, overly long files |
+| 3 | **Naming & clarity** | Unclear names, misleading abstractions, functions exceeding their name's scope |
+| 4 | **Pattern inconsistency** | Same concern handled differently across milestone files (error handling, data fetching, state) |
+| 5 | **Dead code** | Unused functions, unreachable branches, commented-out code, unused imports |
+| 6 | **Abstraction issues** | Over-engineered one-use helpers, repeated inline code warranting extraction, premature/missing abstractions |
+
+**Rules:**
+- Read every file in the diff. No sampling.
+- Every finding references a specific file and line range.
+- Don't flag patterns documented in the constitution.
+- Don't duplicate security or architecture findings.
+- Estimate effort: `quick` (< 30 min, < 50 lines) or `standard` (needs planning).
+- Suggest a concrete approach, not "refactor this."
+- Fewer high-quality findings over many low-signal ones.
+
+**Output format:**
+
+```yaml
+refactoring_scan:
+  files_scanned: N
+  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"
+```
+
+## Step 4: Score Results
+
+**Per-category scoring (security + architecture):**
+
+| Status | Meaning |
+|--------|---------|
+| `passed` | No issues |
+| `warning` | Non-critical issues |
+| `critical` | Exploitable vulnerabilities or architectural blockers |
+| `na` | Category doesn't apply |
+
+**Overall health:**
+
+| Overall | Condition |
+|---------|-----------|
+| `passed` | All categories passed or N/A |
+| `warnings_only` | One+ warnings, zero critical |
+| `issues_found` | One+ critical findings |
+
+Refactoring findings are separate — they never block completion.
+
+## Step 5: Write Health Report
+
+Create `.forge/audits/` if needed. Write to `.forge/audits/milestone-{id}-health-report.md`.
+
+**YAML frontmatter:**
+
+```yaml
+---
+milestone_id: {id}
+milestone_name: "{name}"
+reviewed: "{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
+refactoring:
+  findings_count: N
+  quick_count: N
+  standard_count: N
+total_files_scanned: N
+---
+```
+
+**Body structure:**
+
+```markdown
+# Review Report: {milestone name}
+
+## Executive Summary
+{1-3 sentences: health assessment, key findings, refactoring highlights, recommendation}
+
+## Security Findings
+
+### Category 1: Authentication & Authorization — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat per category. N/A categories: single line "N/A — {reason}"}
+
+## Architecture Findings
+
+### Scalability — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat per dimension}
+
+## Refactoring Opportunities
+
+### Duplication ({N} items)
+| File | Lines | Description | Effort | Approach |
+|------|-------|-------------|--------|----------|
+| ... | ... | ... | quick/standard | ... |
+
+{Repeat per category with findings}
+
+## Public Endpoints
+{Intentionally public endpoints documented during security audit}
+
+## Files Scanned
+{Count and list of all files scanned}
+```
+
+If a previous milestone audit exists in `.forge/audits/`, compare results and note improvements/regressions in the executive summary.
+
+## Step 6: Present Results + Triage Refactoring
+
+### Health Results
+
+Present health status first — this is the gate.
+
+**HEALTHY (all passed):**
+*"Health audit passed. No security vulnerabilities or architectural concerns."*
+
+**NEEDS ATTENTION (critical issues):**
+*"Critical issues found:"*
+Inline top 3 findings per critical category.
+
+**WARNINGS ONLY:**
+*"Passed with warnings — no critical issues, {N} items worth noting. Full report: `.forge/audits/milestone-{id}-health-report.md`."*
+
+### Refactoring Triage
+
+Show findings grouped by category (max 10 initially):
+
+*"{N} refactoring opportunities found:"*
+
+Per category:
+*"**Duplication** ({N}):*
+*1. `src/api/users.ts:42-67` — Duplicate email validation. Quick fix: extract helper. [Accept / Dismiss]*"
+
+User responses:
+- **Accept** → add to backlog
+- **Dismiss** → skip (optionally ask reason to calibrate future scans)
+- **Accept all** → bulk add remaining
+- **Dismiss all** → skip everything
+
+## Step 7: Write Backlog + Route
+
+### Write Refactoring Backlog
+
+Read existing `.forge/refactor-backlog.yml`. Determine next item ID by incrementing from highest existing.
+
+Append accepted items:
+
+```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 file doesn't exist, create from `.forge/templates/refactor-backlog.yml`.
+
+### Route Based on Health Status
+
+#### HEALTHY or WARNINGS ONLY (accepted)
+
+Update `.forge/state/milestone-{id}.yml`: set `current.status` to `complete`.
+Update `.forge/state/index.yml`: set milestone status to `complete`, update `last_updated`.
+
+*"Milestone [{name}] complete. {N} refactoring items in backlog."*
+
+If Beads installed, run `bd complete`.
+
+#### NEEDS ATTENTION (critical issues)
+
+Do NOT mark complete. Present choices:
+
+- **A. Fix critical issues** — return to `planning` in fix mode with findings as requirements
+- **B. Accept risk** — document accepted risks in report, complete the milestone
+
+If A: create fix requirements from findings → route to `planning` → after fix + re-verification → re-run `reviewing`.
+If B: append "Accepted Risks" section to report → complete milestone (same as HEALTHY path).
+
+#### WARNINGS ONLY (user wants to fix)
+
+Create fix requirements from warnings → route to `planning` in fix mode → after fix → re-run `reviewing`.
+
+## Gate Type: Mixed
+
+- **Security critical** → soft gate (user can accept risk)
+- **Architecture critical** → soft gate (user has final authority)
+- **Warnings** → advisory (noted in report, user chooses)
+- **Refactoring items** → never block (cataloged to backlog)
+
+The report documents the decision either way — audit trail.
+
+## Backlog Lifecycle
+
+```
+pending → in_progress → done
+pending → dismissed (during triage or later)
+```
+
+`effort: quick` items → pick up via `quick-tasking`.
+`effort: standard` items → Standard tier flow.
+
+Working a backlog item:
+1. `forge` surfaces it as available
+2. User selects it
+3. Route to `quick-tasking` or Standard tier based on effort
+4. On completion, set `status: done` and `completed` date
+
+## Phase Handoff
+
+After reviewing completes (all paths):
+
+1. Confirm health report written to `.forge/audits/milestone-{id}-health-report.md` and backlog updated
+2. Set `current.status` to `complete` in `.forge/state/milestone-{id}.yml`
+3. Present:
+
+*"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} refactoring items in backlog.*
+
+*Start new work with `/forge` or tackle backlog items anytime."*

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

@@ -7,11 +7,11 @@ description: "Use when building features that touch authentication, user data, e
 
 Security is a requirement, not a feature. Review before shipping.
 
-## When This Skill Triggers
+## Trigger
 
-Ask these 4 questions. If YES to any, run this skill:
+YES to any of these? Run this skill:
 
-1. Does this feature touch **authentication or authorization**?
+1. Does the feature touch **authentication or authorization**?
 2. Does it **store or transmit user data**?
 3. Does it **call external APIs** or accept webhooks?
 4. Does it **handle secrets, keys, or tokens**?
@@ -20,43 +20,43 @@ Ask these 4 questions. If YES to any, run this skill:
 
 ### Authentication & Authorization
 - [ ] Passwords hashed with bcrypt/scrypt/argon2 (never MD5/SHA)
-- [ ] Sessions/tokens expire (configurable, reasonable default)
+- [ ] Sessions/tokens expire with reasonable defaults
 - [ ] Token refresh mechanism exists
 - [ ] Authorization checked server-side before every data access
 - [ ] Failed login attempts rate-limited
 - [ ] Password reset flow doesn't reveal account existence
 
 ### Input Validation & Injection
-- [ ] All user input validated server-side (not just client-side)
+- [ ] All user input validated server-side
 - [ ] SQL queries use parameterized statements (never string concatenation)
 - [ ] HTML output escaped to prevent XSS
-- [ ] File uploads validated: type, size, content (not just extension)
-- [ ] URL parameters sanitized before use
+- [ ] File uploads validated: type, size, content (not extension alone)
+- [ ] URL parameters sanitized
 - [ ] JSON parsing has size limits
 
 ### Secrets Management
-- [ ] Secrets stored in environment variables, never in code
-- [ ] `.env` file in `.gitignore`
+- [ ] Secrets in environment variables, never in code
+- [ ] `.env` in `.gitignore`
 - [ ] No secrets in logs, error messages, or stack traces
-- [ ] API keys scoped to minimum required permissions
-- [ ] Secrets rotated periodically (documented rotation process)
+- [ ] API keys scoped to minimum permissions
+- [ ] Documented rotation process
 
 ### Data Protection
-- [ ] Sensitive data encrypted at rest (if stored)
-- [ ] HTTPS enforced for all data in transit
+- [ ] Sensitive data encrypted at rest
+- [ ] HTTPS enforced for all transit
 - [ ] PII not logged (names, emails, addresses, IPs)
-- [ ] Data retention policy defined (how long, when deleted)
-- [ ] CORS configured to allow only known origins
+- [ ] Data retention policy defined
+- [ ] CORS allows only known origins
 
 ### Dependencies
 - [ ] `npm audit` (or equivalent) passes or vulnerabilities documented
-- [ ] No known vulnerable versions of critical dependencies
-- [ ] Lock file committed (package-lock.json, yarn.lock)
+- [ ] No known vulnerable versions of critical deps
+- [ ] Lock file committed
 - [ ] Dependencies from trusted registries only
 
 ### Error Handling
-- [ ] Error messages don't leak internal details (stack traces, DB schema, file paths)
-- [ ] Unhandled exceptions caught and logged (not displayed to user)
+- [ ] Error messages don't leak internals (stack traces, DB schema, file paths)
+- [ ] Unhandled exceptions caught and logged, not displayed
 - [ ] Rate limiting on all public endpoints
 - [ ] Graceful degradation when external services fail
 

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

@@ -5,30 +5,26 @@ description: "Sync Forge framework files from a local dev repo or NPM. Use when
 
 # Upgrading: Local Dev Sync
 
-Sync framework files from a local Forge source repo into the current project. Use this during Forge development to test changes without publishing to NPM.
+Sync framework files from a local Forge source repo into the current project for testing without publishing to NPM.
 
-For published upgrades, use `npx forge-orkes upgrade` instead.
+For published upgrades, use `npx forge-orkes upgrade`.
 
 ## Step 1: Resolve Source Path
 
 Check if `.forge/dev-source` exists in the project root.
 
-- **If it exists:** read the path from the file (first line, trimmed). Verify the path exists and contains `packages/create-forge/template/`.
-- **If it doesn't exist:** ask the user: *"Where is your local Forge repo? (e.g., ~/Dev/forge)"*
-  - Validate the path has `packages/create-forge/template/`
-  - Save the path to `.forge/dev-source` for next time
+- **Exists:** Read the path (first line, trimmed). Confirm it contains `packages/create-forge/template/`.
+- **Missing:** Ask the user for the local Forge repo path, validate it has `packages/create-forge/template/`, save to `.forge/dev-source`.
 
-The template directory is `{source}/packages/create-forge/template/`.
+Template directory: `{source}/packages/create-forge/template/`.
 
 ## Step 2: File Classification
 
-Files are classified into three categories:
-
 | Category | Paths | Behavior |
 |----------|-------|----------|
-| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite — these are Forge's |
+| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite |
 | **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
-| **Template-only** | `.forge/templates/**` | Overwrite — reference templates |
+| **Template-only** | `.forge/templates/**` | Overwrite |
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements.yml`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
@@ -36,34 +32,30 @@ Files are classified into three categories:
 
 For each framework-owned file in the source template:
 
-1. Read the source file content
-2. Read the local file content (if it exists)
-3. If different → overwrite local with source, report as **updated**
-4. If same → report as **unchanged**
-5. If source has a new file not in local → copy it, report as **added**
-6. If local has a file not in source → report as **removed from template** (don't delete — let user decide)
+1. Read source and local content
+2. Different → overwrite local, report **updated**
+3. Same → report **unchanged**
+4. Source has new file → copy, report **added**
+5. Local has file not in source → report **removed from template** (don't delete -- let user decide)
 
 ## Step 4: Sync Template-Only Files
 
-Same process as Step 3, but for `.forge/templates/**`.
+Same process as Step 3 for `.forge/templates/**`.
 
 ## Step 5: Handle Merge-Owned Files
 
-For `CLAUDE.md`:
+**`CLAUDE.md`:**
 1. Read source and local versions
-2. If different → **do not overwrite**. Instead, summarize what changed in prose (new sections, removed sections, modified text)
-3. Present the summary to the user and let them decide how to merge
+2. If different → summarize changes (new/removed/modified sections) and let the user decide how to merge. Do not overwrite.
 
-For `.claude/settings.json`:
+**`.claude/settings.json`:**
 1. Read source and local versions
-2. Compare the `forge.*` keys only
-3. If forge keys differ → update only `forge.*` keys in local, preserve user's `hooks` and any other custom keys
-4. Update `forge.version` to match the source package version
+2. Compare `forge.*` keys only
+3. If different → update `forge.*` keys in local, preserve user's `hooks` and custom keys
+4. Set `forge.version` to match the source package version
 
 ## Step 6: Report
 
-Present a summary:
-
 ```
 Forge Local Sync Complete
 ─────────────────────────