feat(ci): add limit-aware actions bootstrap for new projects

CHANGELOG.md

@@ -1,12 +1,35 @@
 ## [Unreleased]
 
+### Added
+- **Limit-aware bootstrap templates** — Added workflow templates for `node`,
+  `nextjs`, and `python` projects under
+  `scripts/bootstrap/templates/workflows/limit-aware/`, including:
+  - PR CI templates with baseline required checks and conditional heavy jobs
+  - Nightly security workflows that always run heavy scans
+- **Actions org setup helper** — Added `scripts/bootstrap/actions-org-setup.sh`
+  to validate org/repo Actions endpoints, query billing usage, and upsert:
+  - `ACTIONS_MONTHLY_CAP_MINUTES`
+  - `ACTIONS_WARN_PCT`
+  - `ACTIONS_DEGRADE_PCT`
+- **Actions limits documentation** — Added
+  `docs/guides/actions-limits-strategy.md` and refreshed
+  `docs/guides/organization-setup.md` for the `.github` canonical workflow
+  source.
+
 ### Fixed
 - **IDP init import side effects** — Package root imports no longer trigger `forge-init` writes.
   `initProject` now lives in side-effect-free `patterns/idp/init/project.ts`, CLI execution in
   `patterns/idp/init/cli.ts` is entrypoint-guarded, and IDP barrel exports avoid CLI module
   loading at import time.
 
 ### Changed
+- **Bootstrap contract (new projects)** — `scripts/bootstrap/project.sh` now
+  defaults to `--ci-profile=limit-aware`, requires `--org` and
+  `--actions-cap-minutes` for that profile, and generates limit-aware CI
+  workflows from templates.
+- **Bootstrap path resolution** — Project bootstrapping now resolves source
+  files from repository-root absolute paths, avoiding relative path failures
+  during project generation.
 - **TypeScript ESLint alignment** — Synchronized `@typescript-eslint/eslint-plugin`,
   `@typescript-eslint/parser`, and `typescript-eslint` to `8.57.0` to keep peer
   dependencies compatible in CI installs.

README.md

@@ -134,51 +134,46 @@ npx forge-audit --json --threshold 60            # CI gate mode
 
 ## � GitHub Workflows Optimization
 
-### Organization-Level Reusable Workflows
+### Canonical Workflow Source
 
-Forge-Space Core now provides **centralized reusable workflows** that eliminate duplication across the Forge Space ecosystem:
+Reusable workflows are now centralized in **`Forge-Space/.github`**. This
+repository (`core`) provides bootstrap orchestration and templates for new
+projects.
 
-- **95% reduction** in maintenance overhead
-- **Single source of truth** for all CI/CD logic
-- **Organization-level sharing** via GitHub Actions
-- **Zero duplicated files** across projects
+### Limit-Aware CI (New Orgs + New Projects)
 
-### Available Reusable Workflows
+New projects generated by `scripts/bootstrap/project.sh` default to the
+`limit-aware` CI profile:
 
-#### Core CI/CD Workflows
-- **ci-base.yml** - Unified base CI pipeline with configurable inputs
-- **security-scan.yml** - Comprehensive security scanning and validation
-- **branch-protection.yml** - Automated branch protection and validation
-- **dependency-management.yml** - Centralized dependency updates and auditing
-- **release-publish.yml** - Automated release publishing with version management
+- baseline checks always run: lint, typecheck, unit tests, build, secret scan
+- heavy jobs degrade when Actions usage crosses configured thresholds:
+  - Docker build
+  - E2E
+  - Semgrep
+  - Trivy
+  - CodeQL on PR
+- nightly security workflow still runs heavy scans regardless of degrade mode
 
-#### Usage Examples
+Bootstrap example:
 
-```yaml
-# In your project's .github/workflows/ci.yml
-jobs:
-  ci:
-    uses: Forge-Space/core/.github/workflows/reusable/ci-base.yml@<full-commit-sha>
-    with:
-      project-type: 'gateway'  # or 'mcp', 'webapp', 'patterns'
-      node-version: '22'
-      python-version: '3.12'
-      enable-docker: true
-      enable-security: true
-      enable-coverage: true
+```bash
+./scripts/bootstrap/project.sh my-service node \
+  --org Forge-Space \
+  --actions-cap-minutes 20000
 ```
 
-### Integration Benefits
-- **Instant Updates**: Change once, apply everywhere
-- **Consistency**: Standardized patterns across all projects
-- **Maintenance**: Single point of update for workflow improvements
-- **Quality**: Centralized testing and validation of workflows
-
-### Quick Integration
-1. **Configure Repository Access**: Enable organization access to Forge-Space/core workflows
-2. **Update Workflow References**: Replace local copies with organization references
-3. **Remove Duplicated Files**: Delete any local `-shared.yml` files
-4. **Test and Validate**: Ensure workflows run correctly with new references
+Initialize Actions budget variables for an org:
+
+```bash
+./scripts/bootstrap/actions-org-setup.sh \
+  --org Forge-Space \
+  --actions-cap-minutes 20000
+```
+
+### Related Guides
+
+1. [Organization Setup](docs/guides/organization-setup.md)
+2. [Actions Limits Strategy](docs/guides/actions-limits-strategy.md)
 
 ## � Documentation
 

docs/guides/actions-limits-strategy.md

@@ -0,0 +1,99 @@
+# Actions Limits Strategy (v1)
+
+This guide defines the first-pass GitHub Actions limits strategy for new
+organizations and newly bootstrapped projects.
+
+## Goals
+
+- Reduce risk of hosted-runner exhaustion
+- Keep required CI checks running under budget pressure
+- Degrade non-required heavy jobs when usage is high
+- Keep full security coverage via nightly scans
+
+## Guard Behavior
+
+Reusable workflow source:
+
+- `Forge-Space/.github/.github/workflows/reusable-actions-budget-guard.yml`
+
+Inputs:
+
+- `org`
+- `monthly_cap_minutes`
+- `warn_pct` (default `70`)
+- `degrade_pct` (default `85`)
+
+Outputs:
+
+- `usage_pct`
+- `warn_mode`
+- `degrade_mode`
+- `summary`
+
+Semantics:
+
+- fail-open on billing API/read failures (`degrade_mode=false`)
+- warn mode emits summary signal only
+- degrade mode skips heavy non-required jobs on PR CI
+
+## CI Policy Split
+
+Always run (baseline required checks):
+
+- lint
+- typecheck
+- unit tests
+- build
+- secret scan
+
+Conditionally skipped when `degrade_mode=true`:
+
+- Docker build
+- E2E
+- Semgrep
+- Trivy
+- CodeQL on PR
+
+Always run nightly (schedule + manual dispatch):
+
+- Semgrep
+- Trivy
+- CodeQL
+
+## New Project Bootstrap
+
+`limit-aware` is the default CI profile.
+
+```bash
+./scripts/bootstrap/project.sh my-app node \
+  --org Forge-Space \
+  --actions-cap-minutes 20000
+```
+
+Optional thresholds:
+
+```bash
+./scripts/bootstrap/project.sh my-app nextjs \
+  --org Forge-Space \
+  --actions-cap-minutes 20000 \
+  --actions-warn-pct 70 \
+  --actions-degrade-pct 85
+```
+
+## Organization Setup
+
+Before bootstrapping projects, initialize org/repo variables:
+
+```bash
+./scripts/bootstrap/actions-org-setup.sh \
+  --org Forge-Space \
+  --actions-cap-minutes 20000
+```
+
+## Validation Checklist
+
+- reusable guard workflow resolves from `ORG/.github`
+- budget summary appears in workflow summary
+- degrade mode skips heavy PR jobs only
+- required checks remain green-capable under degrade mode
+- nightly security workflow runs heavy scans independent of degrade mode