env-secrets 0.5.2 → 0.5.4

package/.codex/rules/cicd.md

@@ -25,6 +25,27 @@ You are a CI/CD specialist for TypeScript/JavaScript projects.
 - Integration with package registries and deployment targets.
 - `.github/dependabot.yml` for version and security updates.
 
+## Concurrency
+
+Add a `concurrency` block to every GitHub Actions workflow so that redundant runs triggered by rapid pushes are handled correctly.
+
+- **CI workflows** (lint, test, build): cancel in-progress runs when a newer commit is pushed to the same branch.
+- **Publish/release workflows**: do not cancel in-progress runs — a publish that is already in flight should complete.
+
+```yaml
+# CI workflows (lint, test, build) — cancel superseded runs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Publish/release workflows — let in-flight publishes finish
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+```
+
+Apply the appropriate block at the workflow level (outside any `jobs:` key) for every workflow you create or update.
+
 ## Dependabot
 
 Create a `.github/dependabot.yml` file for the current project. Dependabot monitors dependencies and opens pull requests for updates. Always include both the project's package ecosystem (npm/yarn/pnpm) and `github-actions` so workflow actions stay current.

package/.codex/rules/docs.md

@@ -0,0 +1,98 @@
+# Documentation Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules keep documentation accurate and current using GitHub Markdown by default, or an existing Docusaurus site when the repository already uses one.
+
+---
+
+# Documentation Agent
+
+You are a documentation specialist responsible for keeping product documentation accurate, approachable, and current with the codebase.
+
+## Core Policy
+
+Documentation is part of the product. When application behavior, CLI commands, configuration, architecture, workflows, or operating assumptions change, update the docs in the same change.
+
+## Documentation Stack Decision
+
+Default to a GitHub-readable Markdown documentation set under `docs/`.
+
+Only use Docusaurus when the repository is already using it or the user explicitly asks for it. Detect an existing Docusaurus site from signals such as:
+
+- `docusaurus.config.js`, `docusaurus.config.ts`, `sidebars.js`, or `sidebars.ts`
+- `docs/`, `blog/`, `src/pages/`, or `static/` directories that match a Docusaurus layout
+- `package.json` dependencies referencing `@docusaurus/*`
+
+If Docusaurus is already present:
+
+- Keep using Docusaurus instead of replacing it with plain Markdown.
+- Maintain the existing sidebar, frontmatter, assets, and generated navigation structure.
+- Ensure a `publish-docs` GitHub Actions workflow exists to build and publish the docs site.
+
+If Docusaurus is not present:
+
+- Do not introduce it by default.
+- Keep docs as plain Markdown files that render correctly on GitHub.
+- Ensure `docs/README.md` acts as the documentation index.
+
+## Required Documentation Outcomes
+
+For every meaningful product change, update the documentation that answers these questions:
+
+1. What changed?
+2. Why would a user care?
+3. How does a new user get started?
+4. How does an advanced user configure, extend, debug, or operate it?
+5. What commands, flags, configuration fields, files, or APIs are affected?
+
+Documentation should be structured so a beginner can follow the happy path quickly, while advanced users can find precise reference material without reverse-engineering the code.
+
+## Minimum Documentation Set
+
+For Markdown-based docs, prefer a structure close to:
+
+- `README.md` for the short project overview and entry points
+- `docs/README.md` for the docs index
+- `docs/getting-started.md` or equivalent onboarding material
+- task-specific guides under `docs/`
+- reference material for commands, configuration, architecture, and troubleshooting
+
+For Docusaurus-based docs, preserve the existing site organization and place the same content in the appropriate pages.
+
+## Documentation Quality Bar
+
+- Put the fastest working path first.
+- Use concrete commands, file paths, and examples that match the implementation.
+- Keep terminology and naming consistent with the code and CLI help output.
+- Explain defaults, prerequisites, limitations, and failure modes.
+- Avoid marketing language and vague summaries.
+- Prefer short sections, descriptive headings, and examples over long prose blocks.
+
+## Diagrams
+
+Create Mermaid diagrams when they materially improve understanding.
+
+Required expectations:
+
+- Add a high-level system diagram for non-trivial applications or workflows.
+- If the system has a meaningful data model, configuration model, or persisted entities, document that with Mermaid using `erDiagram` or `classDiagram`.
+- Add sequence diagrams for request flows, background jobs, or user interactions when behavior is easier to understand as a timeline.
+- Add state diagrams when lifecycle or status transitions matter.
+
+Do not add decorative diagrams. Each diagram should answer a real user or operator question and be explained in surrounding text.
+
+## Validation
+
+Before finishing:
+
+- Verify doc links, commands, file paths, flags, and config snippets against the implementation.
+- Update `README.md`, installation docs, command docs, and architecture docs when they are affected.
+- If Docusaurus is used, ensure the docs build still works and the `publish-docs` workflow matches the current site layout.
+- If plain Markdown is used, ensure the docs remain readable on GitHub without requiring a local docs build.
+
+## When Completed
+
+- Summarize which docs were updated.
+- Call out any intentionally deferred documentation gaps.
+- Treat missing docs for shipped behavior as a bug, not an optional follow-up.

package/.codex/rules/git-hooks.md

@@ -0,0 +1,43 @@
+# Git Hooks Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules keep local Git hook orchestration consistent with the repository layout and testing strategy.
+
+---
+
+You are a Git hook specialist. Your role is to establish local Git hook orchestration that complements Ballast linting and testing rules without duplicating ownership.
+
+## Your Responsibilities
+
+1. Select the correct hook tool for the repository layout.
+2. Configure fast checks for `pre-commit`.
+3. Configure unit tests for `pre-push`.
+4. Keep hook configuration current as commands and repo layout evolve.
+5. Keep hook scripts executable and easy to audit.
+
+## Hook Strategy
+
+## Git Hooks
+
+Use `pre-commit` for this repository layout.
+
+- Create `.pre-commit-config.yaml` at the repo root.
+- Install hooks with `pre-commit install`.
+- Install the pre-push hook with `pre-commit install --hook-type pre-push`.
+- Configure `.pre-commit-config.yaml` so fast lint and format checks run on `pre-commit` and unit tests run on `pre-push`.
+- Keep the configuration current with `pre-commit autoupdate`.
+- Verify the hook configuration with `pre-commit run --all-files`.
+
+## Important Notes
+
+- Keep commit-time hooks fast enough that developers do not bypass them.
+- Keep `pre-push` focused on the repo's unit test command and required build step.
+- Update hook commands when lint, format, build, or test scripts change.
+- Verify the hook setup after changes before handing off the repo.
+
+## When Completed
+
+1. Show the user the hook files and commands you added or updated.
+2. Explain how commit-time checks differ from push-time checks.
+3. Explain how to verify the hook setup locally.

package/.codex/rules/github-health-check.md

@@ -0,0 +1,440 @@
+# GitHub Repository Health Check Skill
+
+Runs a comprehensive health audit of the current GitHub repository using the `gh` CLI. Produces a structured report with status indicators and actionable items. Auto-merges safe Dependabot PRs.
+
+---
+
+## Prerequisites
+
+```bash
+# Verify gh is authenticated and repo context is available
+gh auth status
+gh repo view --json name,owner,defaultBranchRef
+```
+
+Capture the repo owner and name for use in API calls:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+OWNER=$(gh repo view --json owner --jq '.owner.login')
+NAME=$(gh repo view --json name --jq '.name')
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+```
+
+---
+
+## Check 1 — GitHub Actions Status (default branch)
+
+```bash
+# Recent workflow runs on the default branch
+gh run list --branch "$DEFAULT_BRANCH" --limit 20 \
+  --json status,conclusion,name,workflowName,createdAt,url \
+  --jq '.[] | {workflow: .workflowName, status: .status, conclusion: .conclusion, created: .createdAt, url: .url}'
+```
+
+**Interpret results:**
+
+- Group runs by workflow name; show the latest run per workflow
+- Flag any workflow whose latest run concluded with `failure` or `cancelled`
+- Flag workflows that haven't run in more than 14 days
+- Show overall summary: X workflows passing, Y failing
+
+```bash
+# Check for any in-progress or queued runs
+gh run list --branch "$DEFAULT_BRANCH" --status in_progress --json workflowName,url
+gh run list --branch "$DEFAULT_BRANCH" --status queued --json workflowName,url
+```
+
+---
+
+## Check 2 — Branch Freshness vs Latest Release
+
+```bash
+# Get the latest release tag
+LATEST_TAG=$(gh release list --limit 1 --json tagName --jq '.[0].tagName // "none"')
+echo "Latest release: $LATEST_TAG"
+
+# Count commits on default branch since last release
+if [ "$LATEST_TAG" != "none" ]; then
+  git fetch --tags 2>/dev/null || true
+  COMMITS_AHEAD=$(git rev-list "${LATEST_TAG}..HEAD" --count 2>/dev/null || echo "unknown")
+  echo "Commits since last release: $COMMITS_AHEAD"
+
+  # Show recent unreleased commits
+  git log "${LATEST_TAG}..HEAD" --oneline 2>/dev/null | head -10 || true
+fi
+
+# Get last release date
+gh release list --limit 1 --json tagName,publishedAt \
+  --jq '.[] | "Tag: \(.tagName)  Published: \(.publishedAt)"'
+```
+
+**Interpret results:**
+
+- If commits ahead > 20: warn that a release may be overdue
+- If last release was more than 30 days ago: note it
+- If no releases exist: note that versioned releases are not configured
+
+---
+
+## Check 3 — Open Pull Requests
+
+```bash
+# List all open PRs with key metadata
+gh pr list --state open --json number,title,author,isDraft,createdAt,labels,headRefName,reviewDecision,statusCheckRollup \
+  --jq '.[] | {
+    number: .number,
+    title: .title,
+    author: .author.login,
+    isDraft: .isDraft,
+    created: .createdAt,
+    branch: .headRefName,
+    review: .reviewDecision,
+    checks: (.statusCheckRollup // [] | {
+      total: length,
+      passing: map(select(.conclusion == "SUCCESS")) | length,
+      failing: map(select(.conclusion == "FAILURE")) | length
+    })
+  }'
+```
+
+**Report:**
+
+- Total open PRs, draft vs ready
+- PRs older than 7 days without activity (stale)
+- PRs with failing checks
+- PRs awaiting review
+
+### Dependabot PR Auto-Merge
+
+```bash
+# Get all open Dependabot PRs
+gh pr list --state open --author "app/dependabot" \
+  --json number,title,headRefName,statusCheckRollup,isDraft,mergeable
+```
+
+For each Dependabot PR returned, apply this decision logic:
+
+1. **Parse the version bump** from the PR title (format: "Bump X from A.B.C to D.E.F"):
+
+   - Extract `from` version and `to` version
+   - Compare the major version (first number): if major version changes → **SKIP** (major upgrade)
+   - If only minor/patch changes → candidate for auto-merge
+
+2. **Check CI status**: all checks must be `SUCCESS` (no failures, no pending)
+
+   ```bash
+   gh pr checks <PR_NUMBER> --json name,state,conclusion
+   ```
+
+3. **Verify not a draft** and **mergeable** state is not `CONFLICTING`
+
+4. **Auto-merge if all conditions pass** (no confirmation needed):
+
+   ```bash
+   gh pr merge <PR_NUMBER> --squash --auto
+   ```
+
+5. **Report each decision**: merged / skipped (major) / skipped (CI failing) / skipped (conflicts)
+
+**Example major version detection:**
+
+- "Bump eslint from 8.57.0 to 9.0.0" → major (8→9) → SKIP
+- "Bump typescript from 5.3.3 to 5.4.0" → minor → merge
+- "Bump lodash from 4.17.20 to 4.17.21" → patch → merge
+
+---
+
+## Check 4 — Code Coverage (Codecov)
+
+```bash
+# Check for codecov configuration file
+ls .codecov.yml codecov.yml .codecov.yaml codecov.yaml 2>/dev/null || echo "No codecov config file found"
+
+# Check for codecov in CI workflows
+grep -rl "codecov" .github/workflows/ 2>/dev/null || echo "No codecov step found in workflows"
+
+# Check README for codecov badge
+grep -i "codecov" README.md 2>/dev/null | head -3 || echo "No codecov badge in README"
+
+# Check if codecov token is configured as a repo secret (presence only, not value)
+gh api "/repos/${OWNER}/${NAME}/actions/secrets" --jq '.secrets[].name' 2>/dev/null | grep -i codecov || echo "No CODECOV secret found"
+```
+
+**Interpret results:**
+
+- If no codecov config AND no codecov in workflows AND no badge: **WARN** — Codecov does not appear to be configured. Recommend adding the `codecov/codecov-action` to CI workflows.
+- If present: confirm coverage reporting is active
+
+---
+
+## Check 5 — Security Alerts
+
+```bash
+# Count open Dependabot security alerts
+gh api "/repos/${OWNER}/${NAME}/dependabot/alerts?state=open&per_page=100" \
+  --jq 'length' 2>/dev/null | xargs -I{} echo "Open Dependabot alerts: {}" || \
+  echo "Could not fetch Dependabot alert count (check repo permissions)"
+
+# Show top severity alerts
+gh api "/repos/${OWNER}/${NAME}/dependabot/alerts?state=open&sort=severity&direction=desc&per_page=10" \
+  --jq '.[] | "[\(.security_advisory.severity | ascii_upcase)] \(.security_advisory.summary) — \(.dependency.package.name)"' 2>/dev/null || true
+
+# Code scanning alerts (SAST / CodeQL)
+gh api "/repos/${OWNER}/${NAME}/code-scanning/alerts?state=open&per_page=100" \
+  --jq 'length' 2>/dev/null | xargs -I{} echo "Open code scanning alerts: {}" || \
+  echo "Code scanning: not enabled or no access"
+
+# Secret scanning alerts
+gh api "/repos/${OWNER}/${NAME}/secret-scanning/alerts?state=open&per_page=100" \
+  --jq 'length' 2>/dev/null | xargs -I{} echo "Open secret scanning alerts: {}" || \
+  echo "Secret scanning: not enabled or no access"
+```
+
+**Interpret results:**
+
+- Open Dependabot security alerts > 0: list them with severity (critical/high first)
+- Code scanning alerts: show count and any critical/high items
+- Secret scanning alerts > 0: flag as **CRITICAL** — leaked secrets need immediate rotation
+- If code scanning is not enabled: recommend enabling CodeQL in GitHub Advanced Security
+
+---
+
+## Check 6 — Snyk Integration
+
+```bash
+# Check for .snyk policy file
+ls .snyk 2>/dev/null && echo "Snyk policy file found: .snyk" || echo "No .snyk file"
+
+# Check CI workflows for Snyk
+grep -rl "snyk" .github/workflows/ 2>/dev/null || echo "No Snyk step found in workflows"
+
+# Check README for Snyk badge
+grep -i "snyk" README.md 2>/dev/null | head -3 || echo "No Snyk badge in README"
+
+# Check for snyk-related secrets
+gh api "/repos/${OWNER}/${NAME}/actions/secrets" --jq '.secrets[].name' 2>/dev/null | grep -i snyk || echo "No SNYK secret found"
+```
+
+**Interpret results:**
+
+- If no `.snyk`, no Snyk in workflows, no badge, and no Snyk secret: **WARN** — Snyk does not appear to be integrated. Recommend adding Snyk for dependency and container vulnerability scanning (snyk.io).
+- If partially configured: note what's present and what's missing
+
+---
+
+## Check 7 — Branch Protection Rules
+
+```bash
+# Check protection rules on the default branch
+gh api "/repos/${OWNER}/${NAME}/branches/${DEFAULT_BRANCH}/protection" 2>/dev/null || \
+  echo "WARNING: No branch protection rules found on ${DEFAULT_BRANCH}"
+
+# Parse and summarize key protections
+gh api "/repos/${OWNER}/${NAME}/branches/${DEFAULT_BRANCH}/protection" 2>/dev/null | \
+  python3 -c "
+import sys, json
+try:
+    p = json.load(sys.stdin)
+    good, bad = [], []
+    if p.get('required_pull_request_reviews'): good.append('PR reviews required')
+    else: bad.append('No required PR reviews')
+    if p.get('required_status_checks'): good.append('Status checks required')
+    else: bad.append('No required status checks')
+    if p.get('enforce_admins', {}).get('enabled'): good.append('Rules enforced for admins')
+    if p.get('allow_force_pushes', {}).get('enabled'): bad.append('Force pushes allowed on main')
+    if p.get('allow_deletions', {}).get('enabled'): bad.append('Branch deletion allowed')
+    for g in good: print('OK:', g)
+    for b in bad: print('WARN:', b)
+except Exception as e: print('Could not parse:', e)
+" 2>/dev/null || true
+```
+
+**Flag missing protections:**
+
+- No required PR reviews: warn
+- No required status checks: warn
+- Force pushes allowed on main: warn
+- No branch protection at all: flag as high priority
+
+---
+
+## Check 8 — Stale Branches
+
+```bash
+# List remote branches not merged to default branch, sorted by last commit date
+git fetch --prune 2>/dev/null || true
+git branch -r --no-merged "origin/${DEFAULT_BRANCH}" \
+  --sort=-committerdate \
+  --format='%(committerdate:relative)|%(refname:short)' 2>/dev/null | \
+  grep -v "HEAD\|${DEFAULT_BRANCH}" | head -20
+
+# Count stale branches (no commits in 30+ days, not yet merged)
+STALE_COUNT=$(git branch -r --no-merged "origin/${DEFAULT_BRANCH}" \
+  --format='%(committerdate:unix)|%(refname:short)' 2>/dev/null | \
+  python3 -c "
+import sys
+from datetime import datetime, timezone
+cutoff = datetime.now(timezone.utc).timestamp() - 30 * 86400
+count = 0
+for line in sys.stdin:
+    parts = line.strip().split('|')
+    if len(parts) == 2 and parts[0].isdigit() and int(parts[0]) < cutoff:
+        count += 1
+print(count)
+" 2>/dev/null || echo "0")
+echo "Stale branches (30+ days, unmerged): $STALE_COUNT"
+```
+
+---
+
+## Check 9 — Repository Housekeeping
+
+```bash
+# Check for essential files
+for f in README.md LICENSE .gitignore .github/dependabot.yml SECURITY.md .github/CODEOWNERS CODEOWNERS; do
+  [ -f "$f" ] && echo "OK: $f" || echo "MISSING: $f"
+done
+
+# Dependabot config check
+if [ -f ".github/dependabot.yml" ]; then
+  echo "Dependabot ecosystems configured:"
+  grep "package-ecosystem" .github/dependabot.yml | sort | uniq -c
+else
+  echo "WARNING: No .github/dependabot.yml — automated dependency updates not configured"
+fi
+
+# Check repo has a description and topics
+gh repo view --json description,repositoryTopics \
+  --jq '"Description: \(.description // "MISSING — add in repo settings")\nTopics: \(.repositoryTopics.nodes | map(.topic.name) | join(", ") | if . == "" then "NONE — add topics for discoverability" else . end)"'
+```
+
+---
+
+## Check 10 — Workflow Health Patterns
+
+```bash
+# Detect consistently failing workflows (>50% failure rate over recent runs)
+gh run list --branch "$DEFAULT_BRANCH" --limit 50 \
+  --json workflowName,conclusion,createdAt \
+  --jq 'group_by(.workflowName) | .[] | {
+    workflow: .[0].workflowName,
+    runs: length,
+    failures: map(select(.conclusion == "failure")) | length
+  } | select(.runs >= 3) |
+  "\(.workflow): \(.failures)/\(.runs) recent runs failed\(if (.failures / .runs) > 0.5 then " ⚠️ CONSISTENTLY FAILING" else "" end)"'
+```
+
+---
+
+## Check 11 — Release & Tag Health
+
+```bash
+# List recent releases
+gh release list --limit 5 --json tagName,publishedAt,isDraft,isPrerelease \
+  --jq '.[] | "\(.tagName) [\(if .isDraft then "DRAFT" elif .isPrerelease then "PRE-RELEASE" else "RELEASED" end)] — \(.publishedAt)"'
+
+# Check for unpublished draft releases
+DRAFT_COUNT=$(gh release list --json isDraft --jq '[.[] | select(.isDraft)] | length' 2>/dev/null || echo "0")
+[ "$DRAFT_COUNT" -gt 0 ] && echo "WARNING: $DRAFT_COUNT unpublished draft release(s)" || true
+```
+
+---
+
+## Check 12 — Actions Permissions & Secrets Health
+
+```bash
+# Check default workflow permissions
+gh api "/repos/${OWNER}/${NAME}/actions/permissions" \
+  --jq '"Actions enabled: \(.enabled)\nDefault permission: \(.default_workflow_permissions // "unknown")"' 2>/dev/null
+
+# List repo secret names and ages (values never shown)
+echo "--- Repository Secrets ---"
+gh api "/repos/${OWNER}/${NAME}/actions/secrets" \
+  --jq '.secrets[] | "\(.name) (last updated: \(.updated_at))"' 2>/dev/null
+
+# Warn about secrets not rotated in 180+ days
+gh api "/repos/${OWNER}/${NAME}/actions/secrets" 2>/dev/null | \
+  python3 -c "
+import sys, json
+from datetime import datetime, timezone
+try:
+    data = json.load(sys.stdin)
+    for s in data.get('secrets', []):
+        updated = s.get('updated_at', '')
+        try:
+            dt = datetime.fromisoformat(updated.replace('Z', '+00:00'))
+            age = (datetime.now(timezone.utc) - dt).days
+            if age > 180:
+                print(f'STALE SECRET ({age} days): {s[\"name\"]} — consider rotating')
+        except: pass
+except: pass
+" 2>/dev/null || true
+```
+
+---
+
+## Generate Health Report
+
+After running all checks, present findings in this structure:
+
+```text
+## GitHub Repository Health Report
+**Repo**: owner/name
+**Date**: <today>
+**Default Branch**: main
+
+---
+### Overall Status: [HEALTHY | NEEDS ATTENTION | CRITICAL]
+
+---
+### CI/CD  ✅/⚠️/❌
+| Workflow | Latest Status | Last Run |
+|----------|--------------|----------|
+| ...      | ✅/❌        | ...      |
+
+---
+### Pull Requests
+- Open PRs: N (D draft, R ready for review)
+- Stale PRs (>7 days, no activity): N
+- Dependabot PRs auto-merged: N (list titles)
+- Dependabot PRs skipped: N (list with reason)
+
+---
+### Security  ✅/⚠️/❌
+- Dependabot alerts: N open (X critical, Y high)
+- Code scanning (CodeQL): enabled/NOT ENABLED
+- Secret scanning: N open alerts
+- Snyk: configured / NOT CONFIGURED ⚠️
+- Branch protection on main: summary of rules
+
+---
+### Code Coverage  ✅/⚠️
+- Codecov: configured / NOT CONFIGURED ⚠️
+
+---
+### Repository Housekeeping  ✅/⚠️
+- Missing essential files: list or "none"
+- Dependabot auto-updates: configured / missing
+- Stale unmerged branches: N
+- Draft releases: N
+
+---
+### Recommended Actions (prioritized)
+1. [CRITICAL] ...
+2. [HIGH] ...
+3. [MEDIUM] ...
+4. [LOW/NICE-TO-HAVE] ...
+```
+
+---
+
+## Edge Cases
+
+- **Private repo without security features**: Some APIs require admin access; note when commands fail with 403/404 and suggest the user checks repo settings manually
+- **Org-managed repos**: Branch protection and secrets may be inherited from org settings; note this if the API returns 403
+- **No releases yet**: Skip release freshness checks; note that versioned releases are not configured
+- **Rate limiting**: If `gh` returns 429, note that data may be incomplete and suggest retrying
+- **Monorepo**: If multiple `package.json` / `go.mod` / `pyproject.toml` found, note this when scanning Dependabot PRs and check all ecosystems are covered in `.github/dependabot.yml`
+- **gh not authenticated**: Exit immediately with instructions: run `gh auth login`
+- **No open PRs**: Confirm the repo is clean; no merging needed

package/.codex/rules/local-dev-env.md

@@ -24,6 +24,53 @@ You are a local development environment specialist for TypeScript/JavaScript pro
 
 ---
 
+## Pull Request Workflow
+
+When the user is creating or landing a pull request as part of local development workflow, treat PR hygiene as part of the job.
+
+### Your Responsibilities
+
+1. **Ensure Copilot is assigned to the PR**
+
+   - When a PR exists or is being created, check whether GitHub Copilot is assigned for code review/agent assistance when the repository workflow expects it.
+   - If Copilot is not assigned, assign it before considering the PR ready.
+   - Do not assume assignment happened automatically; verify it.
+   - For Copilot or any other reviewer, summarize the review comments and requested changes so the user can decide what should be fixed next.
+
+2. **Use a sub-agent to monitor PR checks**
+
+   - After pushing commits or creating/updating a PR, use a sub-agent to watch the PR checks while the main agent continues with other work.
+   - Have the sub-agent report back when checks succeed or when a check fails.
+   - Treat pending or failing checks as part of the task, not as an afterthought.
+   - Do not tell the user the PR is ready until the sub-agent confirms the required checks are green.
+
+3. **Use `gh` to inspect failures**
+
+   - If PR checks fail, use the GitHub CLI to inspect the failing runs, jobs, logs, and annotations.
+   - Prefer `gh pr checks`, `gh run view`, and related `gh` commands so the user gets concrete failure context tied to the PR.
+   - Pass the failing details from the sub-agent back to the main agent, then summarize the failing check, the relevant error, and what needs to be fixed next.
+
+4. **Reply directly to GitHub review comments when fixing them**
+
+   - When a specific GitHub review comment is addressed, reply on that review comment thread directly instead of posting a general summary comment on the PR.
+   - The reply should say what was changed or why the requested change was not made.
+   - Use general PR comments only for overall status or cross-cutting updates, not for resolving line-specific review feedback.
+   - This applies to Copilot review comments and human review comments alike.
+   - Do not stop at making the code change locally; if the review comment was addressed, add the thread reply.
+   - If multiple review comments were addressed, reply on each relevant thread rather than collapsing them into one PR-level summary.
+
+5. **Summarize review asks before changing code**
+   - For Copilot reviews and human reviews alike, summarize the concrete asks, group duplicates, and identify which comments actually require code changes.
+   - If a comment is informational or already satisfied, say that explicitly.
+
+### When to Apply
+
+- When the user asks to create, update, review, or land a PR.
+- When the task includes “open a PR”, “get the PR ready”, “make sure CI passes”, or similar language.
+- When local work is complete and the next step is validating PR readiness.
+
+---
+
 ## Node Version Management (nvm)
 
 When setting up or working on Node.js/TypeScript projects, use **nvm** (Node Version Manager) to ensure consistent Node versions across developers and environments.

package/.codex/rules/local-dev-license.md

@@ -65,9 +65,11 @@ Replace `<YEAR>` with the current year and `<COPYRIGHT HOLDER>` with the author/
 ```markdown
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+Default license for this project: Apache-2.0 (or ISC, BSD-3-Clause, etc.)
 ```
 
+When such a section exists, use the specified license instead of MIT. If both files define a license, prefer `AGENTS.md` (it is agent-facing and typically more authoritative for automation).
+
 ## Example package.json Addition
 
 ```json