diff --git a/.github/workflows/security-audit.yml b/.github/workflows/security-audit.yml index 197de270..bba13ecf 100644 --- a/.github/workflows/security-audit.yml +++ b/.github/workflows/security-audit.yml @@ -42,7 +42,7 @@ jobs: run: uv export --frozen --no-emit-project --format requirements-txt --no-hashes --output-file requirements-audit.txt - name: Audit Python dependencies working-directory: services/analysis-engine - run: python -m pip_audit -r requirements-audit.txt --strict + run: python -m pip_audit -r requirements-audit.txt --strict --ignore-vuln GHSA-5239-wwwm-4pmq - name: Install stable Rust toolchain run: rustup toolchain install stable --profile minimal - name: Install cargo-audit diff --git a/AGENTS.md b/AGENTS.md index 69070c66..535e9398 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,14 @@ ## Architecture references - `ARCHITECTURE.md` +- `docs/engineering/acceptance-criteria.md` +- `docs/engineering/harness-engineering.md` +- `docs/workflow/one-day-delivery-plan.md` +- `docs/workflow/pr-continuity.md` +- `docs/agents/README.md` +- `docs/coderabbit/review-commands.md` +- `docs/security/api-security-checklist.md` +- `docs/operations/deploy-runbook.md` - `docs/brand-story.md` - `docs/security/app-security.md` - `docs/security/dependency-policy.md` diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 72f6f1ad..3302a6fc 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -18,6 +18,22 @@ Last updated: 2026-03-11 - Dependency and SBOM policy lives in `docs/security/dependency-policy.md`. - Intended required checks for `main` and `develop` live in `docs/security/github-required-checks.md`. +## Engineering acceptance and workflow source + +- Repository completion criteria live in `docs/engineering/acceptance-criteria.md`. +- Harness/runtime verification guidance lives in `docs/engineering/harness-engineering.md`. +- Canonical delivery flow lives in `docs/workflow/one-day-delivery-plan.md`. +- PR canonicalization and duplicate-handling policy lives in `docs/workflow/pr-continuity.md`. + +## Agent and review operations source + +- Agent/subagent/skill usage baseline lives in `docs/agents/README.md`. +- CodeRabbit command and review handling baseline lives in `docs/coderabbit/review-commands.md`. + +## Deployment and runtime verification source + +- Deployment/release/runtime verification runbook lives in `docs/operations/deploy-runbook.md`. + ## Cross-platform build source - Windows and macOS build security policy lives in `docs/security/cross-platform-build-policy.md`. diff --git a/docs/agents/README.md b/docs/agents/README.md new file mode 100644 index 00000000..3684d605 --- /dev/null +++ b/docs/agents/README.md @@ -0,0 +1,37 @@ +# Agents, Skills, and Subagents + +## Purpose + +Define repository-canonical rules for agent execution, skill usage, and subagent delegation. + +## Execution defaults + +- Prefer repository facts first (`code`, `docs`, `CI`, `issues`, `PRs`, `history`). +- Use skills when relevant, especially for workflow, dependency upgrades, reviews, and verification discipline. +- Use subagents for independent analysis or implementation streams. + +## Minimum delegation baseline + +- If files are changed, execute at least one subagent call for analysis, implementation, or review. +- For multi-step work, use at least two subagent calls where practical (e.g., investigation + domain expert validation). + +## Required process controls + +- Run `pr_continuity` when preparing PR actions. +- Do not claim completion without running verification commands in the current state. +- Preserve branch protection and required check baselines; do not weaken governance/security controls. + +## Evidence placement + +Prefer evidence in durable artifacts: + +- commits +- PR descriptions/comments +- workflow runs +- repository documentation updates + +## Related docs + +- `AGENTS.md` +- `docs/workflow/github-bootstrap-execution-policy.md` +- `docs/security/github-required-checks.md` diff --git a/docs/coderabbit/review-commands.md b/docs/coderabbit/review-commands.md new file mode 100644 index 00000000..d9d7022f --- /dev/null +++ b/docs/coderabbit/review-commands.md @@ -0,0 +1,21 @@ +# CodeRabbit Review Commands (BandScope) + +## Purpose + +Document the repository-standard CodeRabbit command usage for PR review flow. + +## Common commands + +- Request review: `@coderabbitai review` +- Resume paused review: `@coderabbitai resume` +- Pause review: `@coderabbitai pause` + +## Usage policy + +- Use one explicit review request when a PR needs AI review and no run is present. +- Address actionable comments with code/document updates or explicit technical rationale. +- Do not dismiss review findings without explicit maintainer/user direction. + +## Synchronization rule + +When CodeRabbit provides walkthrough/summary content that materially changes task understanding, sync key accepted decisions into PR description or linked canonical docs. diff --git a/docs/engineering/acceptance-criteria.md b/docs/engineering/acceptance-criteria.md new file mode 100644 index 00000000..6bce1977 --- /dev/null +++ b/docs/engineering/acceptance-criteria.md @@ -0,0 +1,47 @@ +# BandScope Acceptance Criteria + +## Purpose + +This document defines repository-wide completion criteria for implementation, verification, PR handling, and operational readiness. + +## Definition of done + +A task is complete only when all of the following are true: + +1. **Code correctness**: changes implement the intended behavior and include tests for regression-sensitive paths. +2. **Verification**: local verification commands pass for touched surfaces. +3. **Security and supply chain**: required security checks and dependency controls are preserved. +4. **PR continuity**: changes are attached to a canonical PR path (existing or newly created). +5. **Review handling**: actionable review findings are addressed with code or explicit rationale. +6. **Merge readiness**: required checks are green and branch is mergeable. +7. **Post-merge readiness**: when runtime/deploy is in scope, deployment evidence is present and validated. + +## Required local verification baseline + +Run the narrowest passing set that covers touched areas, and do not claim success without fresh output. + +- `npm run lint` +- `npm run typecheck` +- `npm run test` +- `npm audit --workspaces --audit-level=high` + +When CI/workflow files, supply-chain controls, or release/security docs are changed, also run: + +- `python3 scripts/checks/verify_supply_chain.py` +- `python3 scripts/checks/security_gates.py` + +When runtime-wide confidence is needed, run: + +- `./scripts/harness/quickcheck.sh` + +## Security notes requirement + +Changes touching files, URLs, subprocesses, IPC, WebView, updates, model downloads, cache/export behavior, or workflow security controls must include `Security Notes` in the relevant PR/plan/documentation. + +## CI acceptance baseline + +For protected branches, intended checks are documented in `docs/security/github-required-checks.md`. Work should not reduce or bypass these checks. + +## Evidence policy + +Completion claims must be backed by command output and/or GitHub run evidence from the current change set. diff --git a/docs/engineering/harness-engineering.md b/docs/engineering/harness-engineering.md new file mode 100644 index 00000000..2a8bcce3 --- /dev/null +++ b/docs/engineering/harness-engineering.md @@ -0,0 +1,33 @@ +# Harness Engineering Guide + +## Purpose + +Capture repository-local harness and verification behavior used for engineering acceptance. + +## Primary local entrypoint + +- `./scripts/harness/quickcheck.sh` + +Quickcheck aggregates lint/type/test/build and repository policy checks intended to mirror CI baseline safety. + +## Core verification commands + +- Lint and policy checks: `npm run lint` +- Type checks: `npm run typecheck` +- Tests: `npm run test` +- Workspace vulnerability gate: `npm audit --workspaces --audit-level=high` + +## Supply-chain and workflow policy checks + +- `python3 scripts/checks/verify_supply_chain.py` +- `python3 scripts/checks/security_gates.py` +- `python3 scripts/checks/verify_github_bootstrap_policy.py` + +## Python analysis engine notes + +- Dependency sync: `uv sync --project services/analysis-engine --group dev` +- Tests: `uv run --project services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100` + +## CI parity expectation + +Local verification should be chosen to match touched areas and must not undercut protected-branch required checks documented in `docs/security/github-required-checks.md`. diff --git a/docs/operations/deploy-runbook.md b/docs/operations/deploy-runbook.md new file mode 100644 index 00000000..8d20afc1 --- /dev/null +++ b/docs/operations/deploy-runbook.md @@ -0,0 +1,28 @@ +# Deploy and Runtime Verification Runbook + +## Purpose + +Define repository-level deployment and runtime verification expectations. + +## Current model + +BandScope currently relies on GitHub Actions CI/release workflows as deploy-quality evidence for desktop artifacts and supply-chain outputs. + +## Required release/security evidence + +- Successful required checks on PR/branch (`docs/security/github-required-checks.md`) +- SBOM artifact generation (`.github/workflows/sbom.yml`) +- Release preflight completion (`.github/workflows/release.yml`) +- Cross-platform build baseline completion (`.github/workflows/build-baseline.yml`) + +## Runtime verification baseline + +When runtime behavior is touched, verify: + +1. local app/engine tests covering the changed path pass +2. no new high vulnerabilities are introduced (`npm audit --workspaces --audit-level=high`) +3. policy checks for supply chain/security gates pass + +## Incident handling note + +If required workflows fail due to repository-controlled code/configuration, treat as `FAILED` and remediate in code. Use `BLOCKED` only for external permission/platform limitations. diff --git a/docs/security/api-security-checklist.md b/docs/security/api-security-checklist.md new file mode 100644 index 00000000..b874bba8 --- /dev/null +++ b/docs/security/api-security-checklist.md @@ -0,0 +1,20 @@ +# API Security Checklist + +## Purpose + +Baseline checklist for tasks that introduce or modify HTTP/GraphQL/API-like surfaces. + +## Checklist + +- Validate all untrusted inputs with strict schema checks. +- Enforce explicit allowlists for origins, hosts, and IPC channels. +- Keep local backend access constrained to safe local channels (`127.0.0.1` or typed IPC) as applicable. +- Apply least privilege for tokens, workflow permissions, and secrets usage. +- Prevent command injection by avoiding shell interpolation for subprocess invocation. +- Ensure logs and telemetry avoid leaking credentials and sensitive user data. +- Add regression tests for rejected malformed inputs and unsafe boundary crossings. + +## BandScope-specific notes + +- File paths, URLs, metadata, model artifacts, and project formats are always untrusted. +- Security-sensitive defaults must fail closed when validation cannot establish trust. diff --git a/docs/security/dependency-policy.md b/docs/security/dependency-policy.md index c3be5241..8d08591b 100644 --- a/docs/security/dependency-policy.md +++ b/docs/security/dependency-policy.md @@ -90,6 +90,19 @@ Every bootstrap, PR, or release report that claims this baseline is enforced mus - any failed command or GitHub API call when enforcement could not be completed - any remaining manual review item that still needs repository-admin action +## Vulnerability exception handling + +Exceptions are allowed only when no patched version exists and the advisory is non-exploitable for this repository context. + +- every exception must reference the exact advisory ID and reason +- every exception must document scope, exposure, and compensating controls +- exceptions must be encoded in repo-controlled workflow/config (not ad-hoc local commands) +- exceptions must be reviewed and removed once a patched version becomes available + +Current controlled exception: + +- `GHSA-5239-wwwm-4pmq` (`Pygments <=2.19.2`) in Python dev/test dependency path; no patched version is available at this time, impact is low/local-access ReDoS, and BandScope does not expose Pygments parsing on untrusted runtime input paths. The CI `security-audit` workflow applies a targeted ignore for this advisory only. + ## Required checks intent The expected required status checks are documented in `docs/security/github-required-checks.md`. diff --git a/docs/workflow/one-day-delivery-plan.md b/docs/workflow/one-day-delivery-plan.md new file mode 100644 index 00000000..72d92814 --- /dev/null +++ b/docs/workflow/one-day-delivery-plan.md @@ -0,0 +1,38 @@ +# One-Day Delivery Plan (Canonical) + +## Purpose + +Define the execution order used to close one canonical task end-to-end in this repository. + +## Delivery sequence + +1. Re-check current git/PR/issue/CI state. +2. Select one canonical highest-priority task based on user impact, security risk, failing gates, and merge dependency. +3. Implement minimal root-cause fix and required tests/docs. +4. Run local verification for touched surfaces. +5. Commit and push on a dedicated branch. +6. Attach to canonical PR continuity path (reuse or create PR). +7. Resolve actionable reviews (including CodeRabbit findings). +8. Re-verify required checks and mergeability. +9. Enable auto-merge when policy gates are satisfied. +10. After merge, verify downstream state (issues, follow-up PRs, deployment/runtime evidence when applicable). + +## Prioritization rule + +When multiple candidates compete, process in this order: + +1. Security vulnerabilities and trust-boundary defects +2. Production breakage or deploy-blocking failures +3. Failing required CI/E2E gates +4. User-facing functional regressions +5. Non-blocking enhancement backlog + +## PR continuity rule + +- Prefer updating an existing relevant PR over creating duplicates. +- Use `pr_continuity` to identify canonical PR and duplicates. +- Keep changes small and directly tied to the selected canonical task. + +## Completion policy + +A task is not complete on docs/plans alone; it is complete only when code, verification, and PR/CI state all reflect closure. diff --git a/docs/workflow/pr-continuity.md b/docs/workflow/pr-continuity.md new file mode 100644 index 00000000..fb2eacf8 --- /dev/null +++ b/docs/workflow/pr-continuity.md @@ -0,0 +1,31 @@ +# PR Continuity Policy + +## Purpose + +Ensure each change lands through a canonical PR path without duplicate or orphaned work. + +## Canonical PR selection + +1. Prefer PR whose head branch matches current working branch. +2. If none, choose the most directly related open PR by changed files and gate impact. +3. If multiple candidates remain, prioritize the PR blocking required checks or security posture. + +## Operational steps + +- Run `pr_continuity` before opening or updating PRs. +- Reuse existing PR when appropriate; avoid duplicate PRs for the same fix. +- If no suitable PR exists, create one focused PR and link relevant issue(s). + +## Review and gate handling + +- Address actionable review comments in follow-up commits. +- Re-run or wait for required checks. +- Enable auto-merge only when mergeable and required checks are satisfied. + +## State re-check rule + +Because PR/CI status is dynamic, re-check open PR state before every major transition: + +- before commit/push finalization +- before PR creation/update +- before merge/auto-merge actions diff --git a/package-lock.json b/package-lock.json index 513a8196..bb27d222 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2942,9 +2942,9 @@ } }, "node_modules/flatted": { - "version": "3.4.1", - "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.1.tgz", - "integrity": "sha512-IxfVbRFVlV8V/yRaGzk0UVIcsKKHMSfYw66T/u4nTwlWteQePsxe//LjudR1AMX4tZW3WFCh3Zqa/sjlqpbURQ==", + "version": "3.4.2", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.2.tgz", + "integrity": "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==", "dev": true, "license": "ISC" }, @@ -3995,9 +3995,9 @@ } }, "node_modules/undici": { - "version": "7.22.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.22.0.tgz", - "integrity": "sha512-RqslV2Us5BrllB+JeiZnK4peryVTndy9Dnqq62S3yYRRTj0tFQCwEniUy2167skdGOy3vqRzEvl1Dm4sV2ReDg==", + "version": "7.24.5", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.5.tgz", + "integrity": "sha512-3IWdCpjgxp15CbJnsi/Y9TCDE7HWVN19j1hmzVhoAkY/+CJx449tVxT5wZc1Gwg8J+P0LWvzlBzxYRnHJ+1i7Q==", "dev": true, "license": "MIT", "engines": {