forgedock 1.0.4 → 1.0.6

package/templates/devdocs/project/conventions.md

@@ -0,0 +1,158 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, quality-gate]
+---
+
+# Coding Conventions and Standards
+
+This file defines the coding standards, patterns, and anti-patterns for this project. Pipeline agents (build and review) read this file to ensure changes conform to project conventions.
+
+---
+
+## Instructions
+
+Replace the placeholder content below with your project's actual conventions. Be specific — "use async patterns" is less useful than "all database calls must use `async with AsyncSession()` from `app/db.py`".
+
+---
+
+## Language-Specific Standards
+
+### Python
+
+> Fill in your Python conventions.
+
+- **Version**: {e.g., Python 3.12}
+- **Formatter**: {e.g., black (line length 88), isort}
+- **Type hints**: {e.g., "Required on all public functions; use `Optional[X]` not `X | None` for compatibility"}
+- **Import order**: {e.g., stdlib → third-party → local; enforced by isort}
+- **Async**: {e.g., "All database and HTTP I/O must be async — never mix sync/async patterns in the same call chain"}
+- **Error handling**: {e.g., "Raise specific exceptions, not bare `Exception`; always log before re-raising"}
+- **Logging**: {e.g., "Use `structlog` with context fields — never `print()`"}
+
+**Anti-patterns**:
+- {e.g., "`os.system()` — use `subprocess.run(check=True)` instead"}
+- {e.g., "Mutable default arguments — use `None` sentinel and assign in function body"}
+- {e.g., "String concatenation for SQL — always use parameterized queries"}
+
+### TypeScript / JavaScript
+
+> Fill in your TypeScript conventions.
+
+- **Version**: {e.g., TypeScript 5.x}
+- **Formatter**: {e.g., Prettier (single quotes, 100 char line length)}
+- **Strict mode**: {e.g., "Strict TypeScript — `noImplicitAny: true`, `strictNullChecks: true`"}
+- **API calls**: {e.g., "Always use `/api/...` proxy routes — never call `localhost:8000` or hardcoded host:port"}
+- **State**: {e.g., "Server state via SWR/React Query; UI state via Zustand; no global mutable variables"}
+- **Components**: {e.g., "Use named exports for components, default export for pages"}
+
+**Anti-patterns**:
+- {e.g., "`any` type — use `unknown` with type narrowing instead"}
+- {e.g., "Direct DOM manipulation — use React state"}
+- {e.g., "Hardcoded API URLs — always use the `/api` proxy"}
+
+---
+
+## Testing Conventions
+
+> Describe your testing requirements and patterns.
+
+- **Unit tests**: {e.g., "Required for all service-layer functions; use pytest with async fixtures"}
+- **Integration tests**: {e.g., "Required for all API endpoints; use `httpx.AsyncClient` with test DB"}
+- **Coverage**: {e.g., "Minimum 80% line coverage on new code; enforced by CI"}
+- **Test file location**: {e.g., "Co-located with source — `services/api/app/billing/test_credits.py` next to `credits.py`"}
+- **Mocking**: {e.g., "Mock external APIs (Stripe, email) in tests — never hit external services in CI"}
+
+**Test naming convention**:
+```
+test_{function_name}_{scenario}_{expected_outcome}
+
+# Examples:
+test_check_balance_zero_credits_returns_none
+test_check_balance_negative_credits_raises_value_error
+test_check_balance_valid_credits_returns_balance
+```
+
+---
+
+## Git Conventions
+
+See `templates/commit-convention.md` for the full commit message reference.
+
+**Branch naming**:
+- `fix/{slug}-{issue}` for bug fixes
+- `feat/{slug}-{issue}` for features
+- `refactor/{slug}-{issue}` for refactors
+
+**PR rules**:
+- Never target `main` directly
+- Fast-lane PRs target `staging`
+- Feature-lane PRs target `milestone/{slug}`
+- Every PR must close at least one issue
+
+---
+
+## File Organization
+
+> Describe your file organization conventions.
+
+```
+{e.g.:
+services/
+  api/
+    app/
+      {domain}/      ← one directory per domain
+        __init__.py
+        router.py    ← FastAPI router
+        service.py   ← business logic
+        models.py    ← SQLAlchemy models
+        schemas.py   ← Pydantic schemas
+        test_{domain}.py  ← tests
+}
+```
+
+**Rules**:
+- {e.g., "One module per domain — no cross-domain imports at the same level"}
+- {e.g., "Routers only handle HTTP concerns (parsing, response shaping) — business logic in service layer"}
+- {e.g., "Database models in `models.py`, Pydantic request/response schemas in `schemas.py`"}
+
+---
+
+## Security Conventions
+
+> Document security requirements agents must follow.
+
+- {e.g., "All user-supplied strings that touch shell commands must be sanitized — use `shlex.quote()` or `subprocess` with list args"}
+- {e.g., "Never log passwords, tokens, or PII — scrub before logging"}
+- {e.g., "Use parameterized queries for all SQL — no string formatting"}
+- {e.g., "CORS: restrict `allow_origins` to known domains in production — never `*` in prod"}
+- {e.g., "File uploads: validate MIME type and size; never pass user-supplied filenames to `open()`"}
+
+---
+
+## Code Review Standards
+
+> What agents look for when reviewing PRs.
+
+**Blocking findings** (must fix before merge):
+- Runtime errors (uncaught exceptions, type mismatches, null dereferences)
+- Security vulnerabilities (SSRF, injection, exposed secrets)
+- Breaking API contracts (changed response format without consumer update)
+- Missing error handling on external calls
+
+**Non-blocking findings** (tracked as separate issues):
+- Performance improvements
+- Test coverage gaps
+- Documentation gaps
+- Code style violations (unless enforced by CI)
+
+---
+
+## Documentation Standards
+
+> When and how to document code.
+
+- {e.g., "All public functions require docstrings with Args and Returns sections"}
+- {e.g., "Type hints replace docstring parameter descriptions — don't duplicate"}
+- {e.g., "Document the 'why', not the 'what' — code explains what; comments explain intent"}
+- {e.g., "Mark non-obvious workarounds with `# WORKAROUND: {reason} — remove when {condition}`"}

package/templates/devdocs/project/custom-instructions.md

@@ -0,0 +1,73 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, issue, orchestrate, quality-gate]
+---
+
+# Custom Instructions — Binding Project Directives
+
+**This file has the highest precedence of all devdocs.** Instructions here override agent defaults, training knowledge, and all other devdocs files. Agents MUST follow these directives exactly.
+
+---
+
+## How to Use This File
+
+Add directives below in the format:
+
+```markdown
+### {Topic}
+{Clear, specific instruction. Use imperative language: "Always", "Never", "Must".}
+```
+
+Be explicit. Agents follow instructions literally — vague directives produce inconsistent behavior.
+
+---
+
+## Project-Specific Directives
+
+<!-- Add your binding directives below this line. -->
+<!-- Each directive should be a level-3 heading followed by the instruction. -->
+
+### Example: Code Style Override
+
+> **Example — replace or remove this section.**
+> Always use double quotes for strings in Python (not single quotes), even when linters suggest otherwise. This project enforces double quotes in its style guide.
+
+### Example: Testing Requirement
+
+> **Example — replace or remove this section.**
+> Every new function in `services/api/` must include a corresponding unit test. Do not close a build phase without adding tests for changed code. The quality gate will enforce this, but plan for it in the Builder Contract.
+
+### Example: Deployment Constraint
+
+> **Example — replace or remove this section.**
+> Never modify `docker-compose.prod.yml` without also updating `.env.example` with any new environment variables. These two files must stay in sync.
+
+### Example: Forbidden Pattern
+
+> **Example — replace or remove this section.**
+> Never use `os.system()` — always use `subprocess.run()` with `check=True`. The security audit will flag `os.system()` calls as HIGH severity.
+
+---
+
+## Instructions for Reviewers
+
+When `/review-pr` runs, agents read this file and apply its directives when classifying findings. A violation of a `custom-instructions.md` directive is automatically elevated to HIGH severity, regardless of the standard severity classification.
+
+---
+
+## Precedence Reminder
+
+```
+custom-instructions.md (this file)
+    ↑ HIGHEST PRIORITY
+    
+project/*.md (stack, architecture, conventions, glossary)
+agent/*.md (using-forgedock, using-github)
+templates/*.md (issue, pr, commit, review-finding)
+agent memory
+agent defaults
+    ↓ LOWEST PRIORITY
+```
+
+When this file says one thing and another source says another, follow this file.

package/templates/devdocs/project/glossary.md

@@ -0,0 +1,84 @@
+---
+authority: reference
+scope: project
+applies_to: [work-on, review-pr, issue]
+---
+
+# Domain Glossary
+
+This file defines domain-specific terms, abbreviations, and concepts used in this project. Agents read this file to interpret issue descriptions, code comments, and PR reviews accurately.
+
+---
+
+## Instructions
+
+Add terms below in alphabetical order. Each entry should:
+- Define what the term means **in this project's context** (not a generic definition)
+- Note how the term maps to code if applicable (`module`, `table`, `field`)
+- Flag synonyms or similar terms that might cause confusion
+
+---
+
+## ForgeDock Pipeline Terms
+
+> These terms are pre-defined for all ForgeDock projects. Add project-specific terms below.
+
+**Fast Lane**
+: Issues without a milestone. PRs target `staging`. Used for bug fixes, small improvements, and urgent work.
+
+**Feature Lane**
+: Issues with a milestone. PRs target `milestone/{slug}`. Used for large features developed over time.
+
+**Worktree**
+: A git worktree created in `.claude/worktrees/{branch}` for each in-flight issue. Provides isolation between concurrent pipeline runs.
+
+**Review Finding**
+: A GitHub issue created by a `/review-pr` domain agent for a code quality concern. Labeled `review-finding`. Not a merge blocker — addressed in subsequent PRs.
+
+**Terminal State**
+: A label state that signals the pipeline is complete: `workflow:merged`, `workflow:invalid`, `needs-human`, or `workflow:decomposed`.
+
+**FORGE:BUILDER**
+: An HTML comment marker in a GitHub issue comment that signals the build phase is complete. The pipeline searches for this marker to determine resume point.
+
+**Quality Gate**
+: The `/quality-gate` check that runs on changed files before commit. Flags dead code, missing error handling, security anti-patterns, and performance footguns.
+
+---
+
+## Project-Specific Terms
+
+> Add your project's domain terms below. Remove this instruction block when done.
+
+### {Term}
+
+: {Definition in the context of this project. What does it mean? How is it used in code?}
+: **Code**: `{module.ClassName}` or `{table_name.field_name}` if applicable
+: **Also called**: {synonyms or alternative names, if any}
+: **Contrast with**: {similar term that means something different in this project}
+
+---
+
+## Example Entries
+
+> These are examples to illustrate the format. Replace with your actual terms.
+
+**Credit**
+: A unit of consumption that users spend to perform actions (e.g., run a scrape job). Stored as an integer in `users.credits`. One credit = one unit of API compute.
+: **Code**: `services/api/app/billing/credits.py` → `check_balance()`, `deduct()`
+: **Contrast with**: "subscription" (the plan type) and "token" (authentication artifact)
+
+**Blue Container**
+: The currently-serving production container in the blue/green deploy strategy. The Traefik router sends live traffic to blue until green is promoted.
+: **Code**: `docker-compose.prod.yml` → service `api-blue`
+: **Contrast with**: "green container" (staged, not serving traffic yet)
+
+**Webhook**
+: An HTTP callback from an external service (e.g., Stripe) to our API. Webhooks are idempotent — the same event may be delivered more than once.
+: **Code**: `services/api/app/webhooks/`
+: **Important**: Always verify webhook signatures before processing. Store processed event IDs to prevent duplicate processing.
+
+**Slug**
+: A URL-safe, lowercase, hyphenated string derived from a human-readable name. Used for branch names, milestone identifiers, and URL path segments.
+: **Example**: "User Auth v2" → `user-auth-v2`
+: **Code**: Branch pattern `milestone/{slug}` in `forge.yaml → branches.feature_pattern`

package/templates/devdocs/project/stack.md

@@ -0,0 +1,80 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, issue]
+---
+
+# Tech Stack
+
+This file describes the technology stack for this project. Pipeline agents read this file to understand which tools, frameworks, and environments are in use — informing investigation scope, build decisions, and review focus areas.
+
+---
+
+## Instructions
+
+Replace the placeholder content below with your project's actual tech stack. Be specific about versions where they matter for agent behavior (e.g., Python 3.11 vs 3.12 affects type hint syntax; Next.js 13 App Router vs Pages Router affects file structure).
+
+---
+
+## Backend
+
+**Runtime**: {e.g., Python 3.12, Node.js 20, Go 1.22}
+**Framework**: {e.g., FastAPI 0.111, Express 4.x, Gin}
+**Database**: {e.g., PostgreSQL 16, MySQL 8, SQLite, MongoDB}
+**ORM / Query Layer**: {e.g., SQLAlchemy 2.0 async, Prisma, raw SQL}
+**Cache**: {e.g., Redis 7, Memcached, none}
+**Queue / Workers**: {e.g., Celery + Redis, Bull, RQ, none}
+**Auth**: {e.g., JWT + refresh tokens, session cookies, OAuth2}
+
+## Frontend
+
+**Framework**: {e.g., Next.js 15 App Router, React 18, Vue 3, SvelteKit}
+**Styling**: {e.g., Tailwind CSS 3, CSS Modules, styled-components}
+**State Management**: {e.g., Zustand, Redux Toolkit, React Query, SWR, none}
+**API Layer**: {e.g., tRPC, REST with fetch, GraphQL, Axios}
+
+## Infrastructure
+
+**Hosting**: {e.g., single VPS (DigitalOcean), AWS EC2, Vercel, Railway}
+**Containerization**: {e.g., Docker Compose, Kubernetes, none}
+**Reverse Proxy**: {e.g., Traefik, Nginx, Caddy}
+**Deploy Strategy**: {e.g., blue/green, rolling, direct replace}
+**CI/CD**: {e.g., GitHub Actions, CircleCI, none}
+
+## External Services
+
+**Payments**: {e.g., Stripe, LemonSqueezy, none}
+**Email**: {e.g., Resend, SendGrid, SES, none}
+**Storage**: {e.g., S3, Cloudflare R2, local disk}
+**Monitoring**: {e.g., Sentry, Datadog, UptimeRobot}
+**Analytics**: {e.g., PostHog, Umami, GA4, none}
+
+---
+
+## Key Constraints for Agents
+
+> Fill in constraints that affect how agents should behave when working in this stack.
+
+- {e.g., "All database queries must use async SQLAlchemy — never use sync engine"}
+- {e.g., "Frontend API calls must use `/api/...` proxy routes — never call the backend directly with host:port"}
+- {e.g., "Docker named volumes are root-owned by default — always add chown in entrypoint before privilege drop"}
+- {e.g., "No ORM migrations — use raw SQL in `migrations/` with sequential numbering"}
+
+---
+
+## Local Development Setup
+
+> Describe how to get a local dev environment running. Agents use this when verifying changes.
+
+```bash
+# {commands to start the local dev environment}
+# e.g.:
+cp .env.example .env
+docker compose up -d
+npm run dev
+```
+
+**Default URLs**:
+- Frontend: {e.g., http://localhost:3000}
+- API: {e.g., http://localhost:8000}
+- Admin: {e.g., http://localhost:8000/docs (FastAPI Swagger)}

package/templates/devdocs/templates/commit-convention.md

@@ -0,0 +1,147 @@
+---
+authority: recommended
+scope: templates
+applies_to: [work-on, quality-gate]
+---
+
+# Commit Convention Reference
+
+This project follows the **Conventional Commits** specification. All commits must follow this format to enable automated changelog generation and pipeline compatibility.
+
+---
+
+## Format
+
+```
+{type}({scope}): {description} (#{issue_number})
+
+{optional body — explains the "why" in more detail}
+
+{optional footer — breaking changes, co-authors, etc.}
+```
+
+### Required Fields
+
+| Field | Rules |
+|-------|-------|
+| `type` | Required. Lowercase. One of the types below. |
+| `description` | Required. Imperative mood. Lowercase. No period. Under 72 characters. |
+| `#{issue_number}` | Required. Always reference the linked issue. |
+
+### Optional Fields
+
+| Field | Rules |
+|-------|-------|
+| `scope` | Component or module name in parentheses. Optional but recommended. |
+| `body` | Blank line after subject. Explain the "why". Wrap at 72 characters. |
+| `footer` | `BREAKING CHANGE:` or `Co-authored-by:`. |
+
+---
+
+## Commit Types
+
+| Type | Use for | Example |
+|------|---------|---------|
+| `fix` | Bug fixes that correct existing behavior | `fix(billing): prevent division by zero` |
+| `feat` | New features or capabilities | `feat(dashboard): add dark mode toggle` |
+| `refactor` | Code restructuring with no behavior change | `refactor(api): extract pagination to utility` |
+| `docs` | Documentation changes only | `docs(config): add devdocs schema reference` |
+| `chore` | Maintenance tasks (version bumps, CI config) | `chore: bump version to 1.2.0 [skip ci]` |
+| `test` | Adding or updating tests | `test(billing): add coverage for zero-credit edge case` |
+| `perf` | Performance improvements | `perf(scraper): reduce queue memory footprint` |
+| `style` | Code style/formatting (no logic change) | `style: apply black formatting` |
+| `build` | Build system or dependency changes | `build: upgrade to Node 20` |
+| `ci` | CI/CD configuration changes | `ci: add deploy job to workflow` |
+
+---
+
+## Scope Examples
+
+Scope is the component or module affected. Keep it short:
+
+| Scope | Use for |
+|-------|---------|
+| `billing` | Payment, credits, subscription logic |
+| `api` | Backend API routes and handlers |
+| `auth` | Authentication and authorization |
+| `dashboard` | Frontend dashboard pages |
+| `scraper` | Data collection services |
+| `infra` | Docker, CI/CD, deployment configs |
+| `installer` | `bin/forgedock.mjs` onboarding flow |
+| `onboarding` | Setup and initialization logic |
+| `security` | Security hardening changes |
+
+---
+
+## Examples
+
+### Simple fix
+
+```
+fix(billing): prevent division by zero when user credits reach 0 (#42)
+```
+
+### Feature with body
+
+```
+feat(dashboard): add dark mode toggle to settings page (#58)
+
+Users reported eye strain when using the dashboard in low-light environments.
+This adds a persistent dark mode preference stored in localStorage and
+applied via CSS custom properties.
+```
+
+### Breaking change
+
+```
+feat(api)!: change /health endpoint response format (#99)
+
+BREAKING CHANGE: The health endpoint now returns {"status":"ok"} instead
+of {"status":"healthy"}. Update all consumers before deploying.
+```
+
+### Chore (skip CI)
+
+```
+chore: bump version to 1.2.0 [skip ci]
+```
+
+### Multiple authors
+
+```
+fix(scraper): handle empty response from external API (#71)
+
+Co-authored-by: Jane Smith <jane@example.com>
+```
+
+---
+
+## Rules
+
+1. **Imperative mood**: "add" not "added", "fix" not "fixed", "remove" not "removed"
+2. **Lowercase description**: `fix(auth): handle null token` not `fix(auth): Handle Null Token`
+3. **No period** at the end of the description line
+4. **Under 72 characters** on the subject line
+5. **Always reference the issue**: Every commit must include `(#{issue_number})`
+6. **`[skip ci]`**: Only for pure documentation or version bump commits with no code changes
+7. **`BREAKING CHANGE:`**: Always document breaking API/behavior changes in the footer
+
+---
+
+## Anti-Patterns
+
+| Bad | Why | Good |
+|-----|-----|------|
+| `fix: stuff` | Not specific | `fix(auth): handle null refresh token in session middleware (#55)` |
+| `Added dark mode` | Wrong tense, no type, no issue | `feat(dashboard): add dark mode toggle (#58)` |
+| `wip` | Not meaningful | Stage as draft PR; use meaningful commit messages |
+| `fix: fixed the thing that was broken` | Redundant, vague | `fix(api): prevent 500 when payment provider returns null intent (#42)` |
+| `update config` | No type, vague | `chore(infra): add REDIS_URL to docker-compose.prod.yml (#67)` |
+
+---
+
+## CI Integration
+
+The pipeline checks commit messages using conventional commit linting. Non-conforming messages on PRs targeting `staging` or `milestone/*` branches will trigger a quality gate finding.
+
+The `[skip ci]` directive suppresses CI runs — use only when the change has zero code impact (docs, version string update).

package/templates/devdocs/templates/issue.md

@@ -0,0 +1,141 @@
+---
+authority: recommended
+scope: templates
+applies_to: [issue, work-on]
+---
+
+# Issue Template
+
+Use this template when creating GitHub issues. All four mandatory sections (`Problem`, `Affected Files`, `Expected Behavior`, `Acceptance Criteria`) are required for pipeline compatibility — the `/work-on` investigation agent reads these sections to understand scope and locate the right files.
+
+---
+
+## Template
+
+```markdown
+## Problem
+
+{1-3 sentences describing what is wrong or what is missing. Be specific.}
+
+{For bugs: include the error message, observable symptom, or stack trace snippet.}
+{For regressions: "Regression of #{N} — {brief description of original fix}."}
+
+## Root Cause (if known)
+
+{Point to the specific code path. Use `file:line` references.}
+{If unknown: "Root cause unknown — investigation needed."}
+
+## Affected Files
+
+Files that need changes (ordered by dependency — change these in this order):
+
+1. `{filepath}` — {what needs to change}
+2. `{filepath}` — {what needs to change}
+3. `{filepath}` — {what needs to change}
+
+## Expected Behavior
+
+{What should happen after the fix/feature is implemented.}
+
+## Acceptance Criteria
+
+- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion}
+- [ ] No regressions in {related_feature}
+
+## Dependencies
+
+{If this depends on other issues: "Depends on #{N} — {reason}"}
+{If no dependencies: omit this section entirely.}
+
+## Additional Context
+
+{Optional: screenshots, logs, links to error tracking, user reports}
+{Optional: "**Code branch**: `{branch}`" if the code only exists on a specific branch}
+```
+
+---
+
+## Investigation Issue Template
+
+For research, audit, or exploration tasks:
+
+```markdown
+## Scope
+
+{What needs to be investigated and why.}
+
+## Questions to Answer
+
+- [ ] {Specific question 1}
+- [ ] {Specific question 2}
+- [ ] {Specific question 3}
+
+## Starting Points
+
+Files/areas to examine:
+1. `{filepath}` — {why start here}
+2. `{filepath}` — {why start here}
+
+## Deliverable
+
+{What the investigation should produce:}
+- Execution plan with specific sub-issues, OR
+- Root cause analysis with fix recommendation, OR
+- Decision document with trade-offs
+
+## Context
+
+{Background information the investigator needs.}
+```
+
+---
+
+## Title Format
+
+```
+{prefix}: {concise description}
+{prefix}({scope}): {concise description}
+```
+
+| Prefix | Use for |
+|--------|---------|
+| `fix:` | Bug fixes |
+| `feat:` | New features or capabilities |
+| `refactor:` | Code restructuring (no behavior change) |
+| `docs:` | Documentation only |
+| `chore:` | Maintenance (version bumps, CI config) |
+| `investigate:` | Research/audit tasks |
+
+**Examples**:
+- `fix(billing): division by zero when user credits reach 0`
+- `feat: add dark mode toggle to dashboard settings`
+- `investigate: why API p95 latency doubled since last deploy`
+
+---
+
+## Priority Labels
+
+| Label | When to use |
+|-------|------------|
+| `priority:P0` | Production down, data loss, security vulnerability |
+| `priority:P1` | Significant user-facing bug, deploy blocked |
+| `priority:P2` | Minor bug, non-critical enhancement (default) |
+| `priority:P3` | Cosmetic, nice-to-have |
+
+Default to **P2** if unclear.
+
+---
+
+## Mandatory Section Checklist
+
+Before creating the issue, verify:
+
+- [ ] Title follows `{prefix}: {description}` convention
+- [ ] `## Problem` — concrete and specific (not "something is wrong")
+- [ ] `## Affected Files` — every file path has been verified to exist in the repo
+- [ ] `## Expected Behavior` — describes the desired state after the fix
+- [ ] `## Acceptance Criteria` — at least one testable `- [ ]` criterion
+- [ ] Priority label set
+- [ ] Category label set
+- [ ] No duplicate issues exist (check open AND recently closed)