diff --git a/.biomeignore b/.biomeignore new file mode 100644 index 0000000..bddc75c --- /dev/null +++ b/.biomeignore @@ -0,0 +1,6 @@ +# Biome path exclusions (gitignore syntax). +# Biome 2.5 reads files.includes in biome.json, not this file โ€” keep generated trees in both. + +coverage/ +dist/ +.l9/ diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..585946c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,18 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.py] +indent_size = 4 + +[*.md] +trim_trailing_whitespace = false + +[Makefile] +indent_style = tab diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..f0c06b5 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,17 @@ +# Managed by Quantum-L9/.github โ€” do not edit here. +# Edit templates/CODEOWNERS.repo in the .github repo; changes are re-seeded by PR. +# CODEOWNERS is not inheritable, so this file is physically copied per repo. +# +# Path-scoped only. Do not seed `* @Quantum-L9/platform` โ€” that makes every +# file a required review and the whole rule goes inert if the team slug +# cannot resolve. Team slugs verified against the live org +# (gh api orgs/Quantum-L9/teams): only `platform` exists. +# +# Skip this dest when a root CODEOWNERS already exists. + +/.github/ @Quantum-L9/platform @cryptoxdog +/.github/workflows/ @Quantum-L9/platform @cryptoxdog +/infra/ @Quantum-L9/platform @cryptoxdog +/terraform/ @Quantum-L9/platform @cryptoxdog +SECURITY.md @Quantum-L9/platform @cryptoxdog +CODEOWNERS @Quantum-L9/platform @cryptoxdog diff --git a/.github/ISSUE_TEMPLATE/1-bug.yml b/.github/ISSUE_TEMPLATE/1-bug.yml new file mode 100644 index 0000000..2539204 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug.yml @@ -0,0 +1,66 @@ +name: ๐Ÿ› Bug +description: Something behaves incorrectly and you can show it. +title: "bug: " +labels: ["type:bug", "needs:triage"] +body: + - type: markdown + attributes: + value: | + CI pipeline failures go to + [l9-ci-debt-resolver](https://github.com/Quantum-L9/l9-ci-debt-resolver/issues/new) + instead โ€” that component owns failure diagnosis. + + - type: textarea + id: problem + attributes: + label: Problem + description: The symptom you observed, in one or two sentences. Not your theory. + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Error output + description: Traceback, failing assertion, or log line. Redact secrets. + render: shell + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Reproduction + description: Steps from a clean checkout. Best effort is fine. + render: shell + + - type: input + id: version + attributes: + label: Version / commit + description: Release tag or SHA if you have it. + + - type: dropdown + id: severity + attributes: + label: Severity + description: Routes triage. Advisory only โ€” nothing is blocked by this. + options: + - S4 โ€” cosmetic + - S3 โ€” degraded, workaround exists + - S2 โ€” major function broken, no workaround + - S1 โ€” production down, data loss, or security exposure + validations: + required: true + + - type: input + id: regression + attributes: + label: Last known good version + description: If set, implies a bisect range. Leave blank if unknown. + + - type: textarea + id: context + attributes: + label: Anything else + description: Suspected cause, related issues, workaround in use. diff --git a/.github/ISSUE_TEMPLATE/2-feature.yml b/.github/ISSUE_TEMPLATE/2-feature.yml new file mode 100644 index 0000000..41df311 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-feature.yml @@ -0,0 +1,58 @@ +name: โœจ Feature +description: Propose a capability that does not exist yet. +title: "feat: " +labels: ["type:feature", "needs:triage"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: The pain, not the solution. Who is blocked, and on what? + validations: + required: true + + - type: textarea + id: today + attributes: + label: What you do today + description: Current workaround and its cost. + + - type: textarea + id: proposal + attributes: + label: Proposed behavior + description: What should exist. Include the interface if you know it. + validations: + required: true + + - type: dropdown + id: owner + attributes: + label: Which component should own this? + description: Prevents governance from absorbing CI concerns. + options: + - this repo (org governance / community health) + - l9-ci-sdk or l9-ci-core (test, lint, build execution) + - l9-ci-debt-resolver (CI failure diagnosis or remediation) + - l9-ci-debt-intelligence (CI debt measurement) + - unsure + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Options you rejected and why. + + - type: dropdown + id: scope + attributes: + label: Scope + options: + - S โ€” under a day + - M โ€” a few days, one repo + - L โ€” multi-repo or migration + - XL โ€” needs a design doc first + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/3-task.yml b/.github/ISSUE_TEMPLATE/3-task.yml new file mode 100644 index 0000000..b7705f9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-task.yml @@ -0,0 +1,36 @@ +name: ๐Ÿ”ง Task +description: Known work with a known solution โ€” chore, refactor, infra, docs. +title: "chore: " +labels: ["type:task"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: Why this work exists. What degrades if it is never done? + validations: + required: true + + - type: textarea + id: work + attributes: + label: Work + value: | + - [ ] + - [ ] + validations: + required: true + + - type: dropdown + id: kind + attributes: + label: Kind + options: [chore, refactor, infra / IaC, governance, docs, dependency bump] + validations: + required: true + + - type: input + id: blocks + attributes: + label: Blocks / blocked by + placeholder: "blocked by #12, blocks #34" diff --git a/.github/ISSUE_TEMPLATE/4-incident.yml b/.github/ISSUE_TEMPLATE/4-incident.yml new file mode 100644 index 0000000..bf7247d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/4-incident.yml @@ -0,0 +1,90 @@ +name: ๐Ÿšจ Incident +description: Production is degraded or down. File first, investigate second. +title: "incident: " +labels: ["type:incident", "sev:untriaged", "priority:P0"] +assignees: [] +body: + - type: markdown + attributes: + value: | + **Page first, file second.** If customers are affected and nobody is paged, + stop and page on-call. This issue is the written record, not the alarm. + If this is a security compromise, use a private advisory instead โ€” not this form. + + - type: input + id: started + attributes: + label: Detected at (UTC) + placeholder: "2026-07-28T15:04:00Z" + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem + description: Customer-visible symptom. What is broken, for whom, since when? + validations: + required: true + + - type: dropdown + id: severity + attributes: + label: Severity + options: + - S1 โ€” full outage, data loss, or security exposure + - S2 โ€” major degradation, no workaround + - S3 โ€” partial degradation, workaround in place + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Signal + description: Alert name, dashboard link, error rate, sample traceback. + render: shell + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Blast radius + description: Services, regions, tenants, and estimated request or user count. + validations: + required: true + + - type: textarea + id: mitigation + attributes: + label: Mitigation in progress + description: What is being done right now. Update this field as it evolves. + validations: + required: true + + - type: input + id: suspect + attributes: + label: Suspected trigger + description: Deploy, PR, config change, or upstream provider. Link it. + placeholder: "#1184, deployed 14:52Z" + + - type: input + id: commander + attributes: + label: Incident commander + placeholder: "@handle" + validations: + required: true + + - type: checkboxes + id: gates + attributes: + label: Response checklist + options: + - label: On-call paged. + required: true + - label: Status page or stakeholder comms updated, or explicitly not needed. + - label: Timeline is being kept in the comments below. + - label: Postmortem issue will be opened within 48h of resolution. diff --git a/.github/ISSUE_TEMPLATE/ci-failure.yml b/.github/ISSUE_TEMPLATE/ci-failure.yml new file mode 100644 index 0000000..bc3a892 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ci-failure.yml @@ -0,0 +1,86 @@ +name: CI Pipeline Failure +description: Report a CI pipeline failure for triage by the platform team +title: "[CI Failure]: " +labels: ["ci-failure", "triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Use this template for CI pipeline failures that are not explained by a code bug. + For code bugs that cause test failures, use the Bug Report template instead. + + - type: input + id: workflow-run-url + attributes: + label: Workflow Run URL + description: Paste the full URL of the failed GitHub Actions run. + placeholder: "https://github.com/Quantum-L9/l9-ci-core/actions/runs/XXXXXXXXX" + validations: + required: true + + - type: input + id: failed-job + attributes: + label: Failed Job Name + placeholder: "pr-pipeline / security-scan / scorecard" + validations: + required: true + + - type: dropdown + id: trigger + attributes: + label: Triggered By + options: + - Pull Request + - Push to main + - Scheduled (cron) + - Workflow Dispatch + - Tag push + validations: + required: true + + - type: textarea + id: error-output + attributes: + label: Error Output + description: Paste the relevant error section from the failed step. + render: shell + validations: + required: true + + - type: dropdown + id: bisect-attempted + attributes: + label: Bisect Attempted? + options: + - "No โ€” first occurrence" + - "No โ€” intermittent failure" + - "Yes โ€” narrowed to specific commit (paste SHA below)" + - "Yes โ€” cannot reproduce locally" + validations: + required: true + + - type: input + id: bisect-sha + attributes: + label: Bisect SHA (if applicable) + placeholder: "2b330a5aab90cd7781bef08f14c5e7904b61bc56" + + - type: dropdown + id: affected-kernel + attributes: + label: Affected Kernel + options: + - pr-pipeline.yml + - release-publish.yml + - nightly.yml + - pre-commit-ci.yml + - trio-governance.yml + - security.yml + - scorecard.yml + - sbom.yml + - l9-self-ci.yml (inline only) + - Not a kernel call (repo-local workflow) + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9ddf343 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,18 @@ +# Quantum-L9 org-wide issue template chooser config. +# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository +# +# Advisory URL is rewritten per consumer by ops/build-seed-payload.js +# (same SSOT as SECURITY.md). Do not add a fourth security URL. + +blank_issues_enabled: false + +contact_links: + - name: Security Vulnerability Report + url: https://github.com/Quantum-L9/l9-codegraph/security/advisories/new + about: Do not open a public issue for security vulnerabilities. Follow SECURITY.md instead. + - name: Governance / CANONICAL_LAW Question + url: https://github.com/Quantum-L9/Cursor-Governance/blob/main/CANONICAL_LAW.md + about: For questions about governance policy, symlink contracts, or CANONICAL_LAW.md, read the policy source of truth first. + - name: CI Kernel API Contract + url: https://github.com/Quantum-L9/.github/blob/main/workflow-interface-registry.yml + about: For questions about kernel inputs/outputs/versioning, check the machine-readable registry before filing an issue. diff --git a/.github/ISSUE_TEMPLATE/gov-violation.yml b/.github/ISSUE_TEMPLATE/gov-violation.yml new file mode 100644 index 0000000..5765ba3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/gov-violation.yml @@ -0,0 +1,84 @@ +name: Governance Violation +description: Report a violation of CANONICAL_LAW.md policy +title: "[Gov Violation]: " +labels: ["governance", "violation", "triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Use this template to report a detected violation of [CANONICAL_LAW.md](https://github.com/Quantum-L9/Cursor-Governance/blob/main/CANONICAL_LAW.md). + The platform team will triage and enforce. Do NOT use this for general bugs โ€” use the Bug Report template. + + - type: dropdown + id: violation-type + attributes: + label: Violation Type + options: + - Symlink drift (ยง2 โ€” symlinks missing or broken) + - Anti-pattern detected (ยง7 โ€” forbidden patterns present) + - Trio separation breach (ยง3 โ€” model/service/interface cross-import) + - Policy gate failure (CI gate not enforcing policy) + - Workspace wiring failure (ยง8 โ€” workspace config broken) + - Kernel ref violation (@main used instead of @v1) + - Other (describe below) + validations: + required: true + + - type: dropdown + id: canonical-law-section + attributes: + label: CANONICAL_LAW.md Section Violated + options: + - "ยง1 โ€” Unknown/General" + - "ยง2 โ€” Symlink Contract" + - "ยง3 โ€” Trio Separation" + - "ยง4 โ€” Unknown" + - "ยง5 โ€” Unknown" + - "ยง6 โ€” Unknown" + - "ยง7 โ€” Anti-Patterns" + - "ยง8 โ€” Workspace Wiring" + - "ยง9 โ€” Unknown" + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Evidence + description: Paste command output, diff, or log that demonstrates the violation. + render: shell + validations: + required: true + + - type: dropdown + id: affected-repos + attributes: + label: Affected Repository + multiple: true + options: + - l9-ci-core + - Cursor-Governance + - l9-assurance + - .github (org backbone) + - Multiple repos + validations: + required: true + + - type: dropdown + id: severity + attributes: + label: Severity + options: + - Critical (active governance bypass / security impact) + - High (CI not enforcing policy) + - Medium (drift detected but not exploited) + - Low (documentation only) + validations: + required: true + + - type: textarea + id: proposed-fix + attributes: + label: Proposed Fix (optional) + description: If you know how to fix this, describe the resolution. diff --git a/.github/ISSUE_TEMPLATE/seed-ci-failure.yml b/.github/ISSUE_TEMPLATE/seed-ci-failure.yml new file mode 100644 index 0000000..b075b48 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/seed-ci-failure.yml @@ -0,0 +1,57 @@ +name: Seed / auto-seed CI failure +description: A red governance seed or auto-seed PR โ€” ticket, not a chat +title: "[Seed CI]: " +labels: ["ci-failure", "triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Use this when an org seed / auto-seed PR is red (Biome, labels, Semgrep + install, lockfile cache, required-check collision). For a code bug that + happens to fail tests, use Bug Report. For a kernel failure on a + feature PR, use CI Pipeline Failure. + + - type: input + id: repository + attributes: + label: Repository + description: owner/name of the consumer that received the seed + placeholder: Quantum-L9/example-repo + validations: + required: true + + - type: input + id: sha + attributes: + label: SHA + description: Commit SHA of the failing seed head + placeholder: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + validations: + required: true + + - type: input + id: check_url + attributes: + label: Failing check URL + description: Full Actions run or check-run URL + placeholder: "https://github.com/Quantum-L9/example-repo/actions/runs/XXXXXXXXX" + validations: + required: true + + - type: input + id: check_name + attributes: + label: Failing check name + placeholder: "L9 Analysis / Biome (format + lint) โ€” SDK-owned / Node Test Suite" + validations: + required: true + + - type: textarea + id: error-output + attributes: + label: Error Output + description: Paste the relevant error section from the failed step. + render: shell + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE/agent.md b/.github/PULL_REQUEST_TEMPLATE/agent.md new file mode 100644 index 0000000..ee27af5 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/agent.md @@ -0,0 +1,66 @@ + + +## Problem + +Agent or chore change. Evidence is the gate receipt or Actions run linked below. + +Closes # + +## Fix + +Seed / pack / generated change. See Changes by intent. + +## Risk + +- [x] Low โ€” additive, reversible, no data or contract change +- [ ] Medium โ€” touches shared code, config, or a public interface +- [ ] High โ€” breaking change, migration, IAM/network, or irreversible + +Blast radius: seed dests only (missing-only; customized files kept). +Rollback: revert this PR; consumers keep files already written. + +## Evidence + + + +``` +n/a โ€” because this is a generated seed / chore PR; see the Actions run +``` + +https://github.com/${GITHUB_REPOSITORY}/actions + +## Gates + +- [ ] Regression test added that fails without this fix โ€” n/a โ€” because seed / chore, no product behavior change +- [x] No secrets, tokens, or customer data in code, tests, fixtures, or logs +- [ ] `semgrep` clean, or findings triaged below โ€” n/a โ€” because pack seed does not change product code +- [ ] New IAM / workflow permissions are least privilege and enumerated โ€” n/a โ€” because no new write scopes +- [ ] Third-party actions pinned to a full commit SHA โ€” n/a โ€” because caller pins are unchanged or SHA-pinned +- [ ] Public interface change is documented and versioned โ€” n/a โ€” because no public interface change +- [ ] Observability exists for the new path (metric, log, trace, or alert) โ€” n/a โ€” because no new runtime path + +## Reviewer focus + +Confirm dests are missing-only / replaceable-stock, and default categories +still omit LICENSE, FUNDING, labels.yml, and on-org-update.yml. + +## Changes by intent + + + +**Added** +- seed dests โ€” missing-only org pack + +**Modified** +- n/a + +**Deleted** +- n/a + +## Files touched + + +_pending โ€” the bot fills this in on push_ + diff --git a/.github/governance/execution-profiles.yaml b/.github/governance/execution-profiles.yaml new file mode 100644 index 0000000..cadb0b4 --- /dev/null +++ b/.github/governance/execution-profiles.yaml @@ -0,0 +1,61 @@ +{ + "schema": "l9.execution-profiles/v1", + "profiles": { + "pr_fast": { + "sdk_profile": "ci_fast", + "strict": true, + "default_mode": "blocking", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["pull_request", "workflow_dispatch"] + }, + "merge": { + "sdk_profile": "ci_fast", + "strict": true, + "default_mode": "blocking", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["push", "workflow_dispatch"] + }, + "nightly": { + "sdk_profile": "ci_deep", + "strict": true, + "default_mode": "advisory", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["schedule", "workflow_dispatch"] + }, + "release": { + "sdk_profile": "ci_deep", + "strict": true, + "default_mode": "blocking", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["push", "workflow_dispatch"] + }, + "supply_chain": { + "sdk_profile": "ci_deep", + "strict": true, + "default_mode": "blocking", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["schedule", "workflow_dispatch"] + }, + "agent": { + "sdk_profile": "ci_fast", + "strict": false, + "default_mode": "advisory", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["workflow_dispatch", "pull_request"] + }, + "l4_local": { + "sdk_profile": "ci_fast", + "strict": false, + "default_mode": "advisory", + "providers": ["semgrep"], + "policy": "", + "allowed_events": ["workflow_dispatch"] + } + } +} diff --git a/.github/governance/promotion-policy.yaml b/.github/governance/promotion-policy.yaml new file mode 100644 index 0000000..02c4ed5 --- /dev/null +++ b/.github/governance/promotion-policy.yaml @@ -0,0 +1,17 @@ +{ + "schema": "l9.promotion-policy/v1", + "transitions": { + "disabled": ["shadow"], + "shadow": ["advisory", "disabled"], + "advisory": ["blocking", "shadow"], + "blocking": ["advisory"] + }, + "requirements": { + "minimum_observation_runs": 20, + "minimum_observation_days": 7, + "maximum_contract_failures": 0, + "maximum_artifact_validation_failures": 0, + "approval_required": true, + "approval_team": "@Quantum-L9/platform" + } +} diff --git a/.github/governance/provider-requiredness.yaml b/.github/governance/provider-requiredness.yaml new file mode 100644 index 0000000..a8194e4 --- /dev/null +++ b/.github/governance/provider-requiredness.yaml @@ -0,0 +1,20 @@ +{ + "schema": "l9.provider-requiredness/v1", + "profiles": { + "pr_fast": { + "semgrep": true + }, + "merge": { + "semgrep": true + }, + "nightly": { + "semgrep": false + }, + "release": { + "semgrep": true + }, + "supply_chain": { + "semgrep": true + } + } +} diff --git a/.github/governance/quality-thresholds.yaml b/.github/governance/quality-thresholds.yaml new file mode 100644 index 0000000..64ef6f3 --- /dev/null +++ b/.github/governance/quality-thresholds.yaml @@ -0,0 +1,27 @@ +{ + "schema": "l9.quality-threshold-selection/v1", + "profiles": { + "pr_fast": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "merge": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "nightly": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "release": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "supply_chain": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "agent": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + }, + "l4_local": { + "sdk_policy": ".github/governance/semgrep-finding-policy.yaml" + } + }, + "note": "Core selects an SDK policy file but never evaluates finding thresholds itself. sdk_policy is the pinned finding-policy dest the seeder also writes." +} diff --git a/.github/governance/rule-modes.yaml b/.github/governance/rule-modes.yaml new file mode 100644 index 0000000..a2afe9b --- /dev/null +++ b/.github/governance/rule-modes.yaml @@ -0,0 +1,21 @@ +{ + "schema": "l9.rule-modes/v1", + "defaults": { + "pr_fast": "blocking", + "merge": "blocking", + "nightly": "advisory", + "release": "blocking", + "supply_chain": "blocking", + "agent": "advisory", + "l4_local": "advisory" + }, + "provider_overrides": { + "semgrep": {} + }, + "allowed_modes": [ + "blocking", + "advisory", + "shadow", + "disabled" + ] +} diff --git a/.github/governance/semgrep-finding-policy.yaml b/.github/governance/semgrep-finding-policy.yaml new file mode 100644 index 0000000..2a21818 --- /dev/null +++ b/.github/governance/semgrep-finding-policy.yaml @@ -0,0 +1,11 @@ +{ + "schema": "l9.finding-policy/v1", + "metadata": { + "version": "1.0.0", + "status": "authoritative" + }, + "defaults": { + "mode": "unresolved" + }, + "rules": {} +} diff --git a/.github/governance/semgrep-identity-map.yaml b/.github/governance/semgrep-identity-map.yaml new file mode 100644 index 0000000..1ec88cf --- /dev/null +++ b/.github/governance/semgrep-identity-map.yaml @@ -0,0 +1,9 @@ +{ + "schema": "l9.identity-map/v1", + "metadata": { + "provider_id": "semgrep", + "version": "1.0.0", + "status": "authoritative" + }, + "rules": {} +} diff --git a/.github/governance/waivers.yaml b/.github/governance/waivers.yaml new file mode 100644 index 0000000..dce98fa --- /dev/null +++ b/.github/governance/waivers.yaml @@ -0,0 +1,4 @@ +{ + "schema": "l9.waivers/v1", + "waivers": [] +} diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..302ac5c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,81 @@ + + +## Problem + + + +``` +paste the error / failing output here, or delete this block and describe the gap +``` + +Closes # + +## Fix + + + +## Risk + + + +- [ ] Low โ€” additive, reversible, no data or contract change +- [ ] Medium โ€” touches shared code, config, or a public interface +- [ ] High โ€” breaking change, migration, IAM/network, or irreversible + +Blast radius: +Rollback: + +## Evidence + + + +``` +$ pytest -q +$ ruff check . && pyright +``` + +## Gates + + + +- [ ] Regression test added that fails without this fix +- [ ] No secrets, tokens, or customer data in code, tests, fixtures, or logs +- [ ] `semgrep` clean, or findings triaged below +- [ ] New IAM / workflow permissions are least privilege and enumerated +- [ ] Third-party actions pinned to a full commit SHA +- [ ] Public interface change is documented and versioned +- [ ] Observability exists for the new path (metric, log, trace, or alert) + +## Reviewer focus + + + +## Changes by intent + + + +**Added** +- `path/to/new_file.py` โ€” why this file needs to exist + +**Modified** +- `path/to/existing.py` โ€” what changed in it and why + +**Deleted** +- `path/to/dead.py` โ€” why it is safe to remove + +## Files touched + + + + +_pending โ€” the bot fills this in on push_ + diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml new file mode 100644 index 0000000..24bc993 --- /dev/null +++ b/.github/workflows/governance.yml @@ -0,0 +1,45 @@ +# Managed by Quantum-L9/.github. Pinned to a tag so main can move safely. +# +# This file should never need editing again. Governance logic lives in +# Quantum-L9/.github/.github/workflows/governance-*.yml; shipping a change means +# force-moving the v1 tag there, not touching this file. +# +# Pin record (ops/governance-v1-pin.txt): +# Quantum-L9/.github/.github/workflows/governance-pr.yml@v1 +# Quantum-L9/.github/.github/workflows/governance-issue.yml@v1 +# tag SHA 7ed3ab8650583f6659a6caf061eae77dbd3ed1be +# Preflight: `git ls-remote https://github.com/Quantum-L9/.github.git refs/tags/v1` +# must match that SHA before re-seeding this caller. +# +# SECRETS: a called workflow does NOT inherit caller secrets automatically. +# Both callees use only GITHUB_TOKEN. Do not add blank `secrets: inherit`. +# If a callee later needs a real secret, add a named `secrets:` entry. +# +# Permission validation runs BEFORE `if:` skip. Both jobs must declare +# job-level permissions or a partial grant startup_fails on the unused job. +# +# ACCESS: if this caller fails before any step runs, check the Actions policy on +# THIS repo. `gh api repos/OWNER/REPO/actions/permissions` + +name: Governance + +on: + pull_request: + types: [opened, edited, synchronize, reopened, ready_for_review] + issues: + types: [opened, edited, reopened] + +jobs: + pr: + if: github.event_name == 'pull_request' + permissions: + contents: read + pull-requests: write + uses: Quantum-L9/.github/.github/workflows/governance-pr.yml@3e841ea4f7f8be2a8c9fc45cad5bed46fe801d08 # v1 + + issue: + if: github.event_name == 'issues' + permissions: + contents: read + issues: write + uses: Quantum-L9/.github/.github/workflows/governance-issue.yml@3e841ea4f7f8be2a8c9fc45cad5bed46fe801d08 # v1 diff --git a/.github/workflows/l9-analysis.yml b/.github/workflows/l9-analysis.yml new file mode 100644 index 0000000..d5c4c73 --- /dev/null +++ b/.github/workflows/l9-analysis.yml @@ -0,0 +1,263 @@ +# L9 analysis caller (TEMPLATE โ€” copy into your repo at .github/workflows/l9-analysis.yml) +# +# Preferred hop when Core pins match: Quantum-L9/l9-ci-core +# `.github/workflows/analyze-semgrep.yml@v2` (docs/templates/l9-analysis.yml). +# This pack file stays on the SHA-pinned inline + publish topology so +# `make sync-core` cannot silently change callee inputs. Stack-selects +# `--config` (p/python vs p/javascript+p/typescript). If `.github/governance/` +# is missing, job `governance-pack-missing` is the one blocking check. +# +# Topology (this is the wiring that actually works): +# job analyze -> generates the semgrep report and runs the SDK pipeline in ONE +# job so the freshly-generated report is on the same filesystem +# (the reusable normalize workflow re-checks-out github.sha and +# would NOT see an uncommitted report). +# job publish -> calls Core's publish-analysis.yml, which DOWNLOADS the +# uploaded artifact (no report-in-tree needed) and publishes the +# GitHub check per the resolved governance mode. +# +# Prerequisite: copy docs/templates/governance/*.yaml into THIS repo at +# .github/governance/ (that is the CI instantiation pack the resolver reads). + +name: L9 Analysis + +on: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: l9-analysis-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +env: + # Core pin is the literal SHA/tag on every uses: Quantum-L9/l9-ci-core/...@... + # line below. GitHub Actions does NOT expand env/expressions in uses: refs โ€” + # do not add an L9_CORE_REF env expecting it to repin; edit each uses: line + # (or run ops/sync-v2-starters.sh) instead. Current pin: + # f88116503430aa18992b70d8d31063e34ff97ef1 + # Match the event: pr_fast for pull_request, merge for push, nightly/release/ + # supply_chain as appropriate. Must be allowed_events in execution-profiles.yaml. + L9_PROFILE: "pr_fast" + L9_MATRIX_ID: "pr-semgrep" + +jobs: + preflight: + name: Detect stack + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + outputs: + has_governance: ${{ steps.detect.outputs.has_governance }} + semgrep_configs: ${{ steps.detect.outputs.semgrep_configs }} + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin "https://github.com/${REPOSITORY}.git" + auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 | tr -d '\n')" + git -c protocol.version=2 \ + -c "http.https://github.com/.extraheader=${auth_header}" \ + fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + - id: detect + name: Detect governance pack and stack + run: | + set -euo pipefail + if [ -d .github/governance ]; then + echo "has_governance=true" >> "$GITHUB_OUTPUT" + else + echo "has_governance=false" >> "$GITHUB_OUTPUT" + fi + configs=() + if [ -f pyproject.toml ] || [ -f requirements.txt ]; then + configs+=(--config p/python) + fi + if [ -f package.json ]; then + configs+=(--config p/javascript --config p/typescript) + fi + if [ ${#configs[@]} -eq 0 ]; then + configs=(--config p/python --config p/javascript --config p/typescript) + fi + echo "semgrep_configs=${configs[*]}" >> "$GITHUB_OUTPUT" + + governance-pack-missing: + name: L9 Analysis + needs: preflight + if: needs.preflight.outputs.has_governance != 'true' + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + steps: + - name: Publish remediable signal + run: | + set -euo pipefail + echo "::error::governance-pack-missing โ€” .github/governance/ is absent. Seed l9-ci-pack (categories=l9-ci-pack) or copy l9-ci-pack/governance/*.yaml, then re-run." + exit 1 + + analyze: + name: Analyze (semgrep -> SDK) + needs: preflight + if: needs.preflight.outputs.has_governance == 'true' + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + outputs: + mode: ${{ steps.gov.outputs.mode }} + enabled: ${{ steps.gov.outputs.enabled }} + artifact-name: ${{ steps.names.outputs.artifact-name }} + governance-digest: ${{ steps.gov.outputs.governance-digest }} + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin \ + "https://x-access-token:${TOKEN}@github.com/${REPOSITORY}.git" + git -c protocol.version=2 fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + git remote set-url origin "https://github.com/${REPOSITORY}.git" + + - id: gov + name: Resolve governance (Core) + uses: Quantum-L9/l9-ci-core/.github/actions/resolve-governance@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + profile: ${{ env.L9_PROFILE }} + provider: semgrep + event-name: ${{ github.event_name }} + repository: ${{ github.repository }} + ref: ${{ github.ref }} + governance-root: .github/governance + + - id: names + name: Resolve artifact name + env: + MATRIX_ID: ${{ env.L9_MATRIX_ID }} + run: | + set -euo pipefail + echo "artifact-name=l9-semgrep-${MATRIX_ID}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT" + + - name: Run semgrep (produce raw report) + if: steps.gov.outputs.enabled == 'true' + run: | + set -euo pipefail + # AGENTS.md pins the supported Semgrep range; installing bare + # `semgrep` would float onto a future major and silently change + # findings/normalization between runs of the same commit. + python -m pip install --upgrade pip 'semgrep>=1.100.0,<2.0.0' + mkdir -p "artifacts/raw/semgrep/${L9_MATRIX_ID}" + # Stack-selected by job preflight. Word-split is intentional. + # shellcheck disable=SC2086 + semgrep scan ${SEMGREP_CONFIGS} \ + --json \ + --output "artifacts/raw/semgrep/${L9_MATRIX_ID}/report.json" \ + --error --quiet || true + env: + L9_MATRIX_ID: ${{ env.L9_MATRIX_ID }} + SEMGREP_CONFIGS: ${{ needs.preflight.outputs.semgrep_configs }} + + - id: sdk + name: Provision immutable SDK + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/provision-sdk@f88116503430aa18992b70d8d31063e34ff97ef1 + + - name: Normalize provider report + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + executable: ${{ steps.sdk.outputs.executable }} + operation: semgrep-normalize + input: artifacts/raw/semgrep/${{ env.L9_MATRIX_ID }}/report.json + output: .l9/runtime/${{ env.L9_MATRIX_ID }}/finding-bundle.json + root: . + snapshot-id: ${{ github.sha }} + revision: ${{ github.sha }} + strict: ${{ steps.gov.outputs.strict }} + required: ${{ steps.gov.outputs.required-provider }} + policy: ${{ steps.gov.outputs.sdk-policy }} + + - name: Validate canonical bundle + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/validate-bundle@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + executable: ${{ steps.sdk.outputs.executable }} + bundle: .l9/runtime/${{ env.L9_MATRIX_ID }}/finding-bundle.json + + - name: Project agent-review payload + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/invoke-sdk@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + executable: ${{ steps.sdk.outputs.executable }} + operation: bundle-project-agent-payload + input: .l9/runtime/${{ env.L9_MATRIX_ID }}/finding-bundle.json + output: .l9/runtime/${{ env.L9_MATRIX_ID }}/agent-review-payload.json + strict: ${{ steps.gov.outputs.strict }} + + - id: route + name: Route artifacts + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/route-artifacts@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + provider: semgrep + matrix-id: ${{ env.L9_MATRIX_ID }} + raw-report: artifacts/raw/semgrep/${{ env.L9_MATRIX_ID }}/report.json + bundle: .l9/runtime/${{ env.L9_MATRIX_ID }}/finding-bundle.json + agent-payload: .l9/runtime/${{ env.L9_MATRIX_ID }}/agent-review-payload.json + destination-root: artifacts + + - name: Build artifact manifest + if: steps.gov.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/actions/build-artifact-manifest@f88116503430aa18992b70d8d31063e34ff97ef1 + with: + provider: semgrep + matrix-id: ${{ env.L9_MATRIX_ID }} + sdk-revision: ${{ steps.sdk.outputs.sdk-revision }} + bundle: ${{ steps.route.outputs.bundle }} + agent-payload: ${{ steps.route.outputs.agent-payload }} + raw-directory: ${{ steps.route.outputs.raw-directory }} + output: artifacts/metadata/${{ env.L9_MATRIX_ID }}/artifact-manifest.json + + - name: Upload analysis artifact set + if: steps.gov.outputs.enabled == 'true' + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: ${{ steps.names.outputs.artifact-name }} + path: | + artifacts/raw/semgrep/${{ env.L9_MATRIX_ID }}/ + artifacts/l9/${{ env.L9_MATRIX_ID }}/ + artifacts/metadata/${{ env.L9_MATRIX_ID }}/ + if-no-files-found: error + retention-days: 14 + + publish: + name: Publish analysis (Core) + needs: [preflight, analyze] + if: needs.preflight.outputs.has_governance == 'true' && needs.analyze.outputs.enabled == 'true' + uses: Quantum-L9/l9-ci-core/.github/workflows/publish-analysis.yml@f88116503430aa18992b70d8d31063e34ff97ef1 + permissions: + actions: read + checks: write + contents: read + with: + artifact-name: ${{ needs.analyze.outputs.artifact-name }} + profile: pr_fast + mode: ${{ needs.analyze.outputs.mode }} + provider: semgrep + matrix-id: pr-semgrep + governance-digest: ${{ needs.analyze.outputs.governance-digest }} + repository-revision: ${{ github.sha }} + workflow-result: ${{ needs.analyze.result }} diff --git a/.github/workflows/l9-lint-test-node.yml b/.github/workflows/l9-lint-test-node.yml new file mode 100644 index 0000000..3cb019a --- /dev/null +++ b/.github/workflows/l9-lint-test-node.yml @@ -0,0 +1,198 @@ +# L9 consumer lint + test workflow for Node.js / TypeScript +# +# Copy into the CONSUMER repo at `.github/workflows/l9-lint-test-node.yml`. +# Org-distributed copy of Quantum-L9/l9-ci-core presets/typescript +# `.github/workflows/l9-lint-test.yml`. Do not invent a second lint owner. +# +# Formatter/linter ownership: Biome owns JS/TS/JSON (format + lint) via the +# SDK-owned reusable workflow below. ESLint is NOT a second formatter owner +# here. Type checking (tsc) and the repository test suite stay in this repo. +# +# Org-seed safety (Cursor-Governance#276 remediating): +# - Biome always runs. It needs no Node package. +# - `typecheck` / `test` run only when a root `package.json` exists. +# `actions/setup-node` with `cache: npm` hard-fails +# ("Dependencies lock file is not found") before any skip guard, so those +# jobs must not start on Python-only / no-Node consumers. +# - The test job is named `Node Test Suite`, not `Test Suite`, so it cannot +# collide with a required Python pytest context. +# +# Conventions: +# - Immutable event-revision checkout (no floating action ref) +# - SDK reusable workflow pinned to a full 40-char commit SHA +# - Least privilege (contents: read only) +name: L9 Lint and Test (Node) +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +# โ”€โ”€ CONFIGURABLE: agent sets these during activation โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +env: + NODE_VERSION: "20" + PACKAGE_MANAGER: "npm" + SOURCE_DIR: "." + HAS_TYPESCRIPT: "true" + +permissions: + contents: read + +concurrency: + group: l9-lint-test-node-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + # Biome (format + lint + import organization) is owned by the SDK reusable + # workflow โ€” a single read-only gate with a checksum-verified biome binary + # and zero external actions. Reusable-workflow inputs cannot read `env:`, so + # scan-path and the rollout flag are set literally here. + biome: + name: Biome (format + lint) โ€” SDK-owned + permissions: + contents: read + uses: Quantum-L9/l9-ci-sdk/.github/workflows/l9-biome-scan.yml@f546f122d33601ea5a4b2592e3482c5c39eddd82 + with: + scan-path: "." + # Advisory-to-blocking rollout: false = full scan + annotate + exit 0. + # Flip to true to make Biome findings blocking once the repo is clean. + enforce-biome: false + + detect-node: + name: Detect Node package + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + outputs: + has_package: ${{ steps.detect.outputs.has_package }} + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin "https://github.com/${REPOSITORY}.git" + auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 | tr -d '\n')" + git -c protocol.version=2 \ + -c "http.https://github.com/.extraheader=${auth_header}" \ + fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + + - id: detect + name: Detect root package.json + run: | + set -euo pipefail + if [ -f package.json ]; then + echo "has_package=true" >> "$GITHUB_OUTPUT" + else + echo "has_package=false" >> "$GITHUB_OUTPUT" + echo "::notice::no root package.json; skipping Node typecheck and tests" + fi + + typecheck: + name: Type Check (tsc --noEmit) + needs: detect-node + if: needs.detect-node.outputs.has_package == 'true' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin "https://github.com/${REPOSITORY}.git" + # Authenticate with a per-fetch Authorization header instead of + # embedding the token in the remote URL, so the credential is never + # written to the remote URL or .git/config (mirrors actions/checkout). + auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 | tr -d '\n')" + git -c protocol.version=2 \ + -c "http.https://github.com/.extraheader=${auth_header}" \ + fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + + - name: Set up Node + uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0 + with: + node-version: ${{ env.NODE_VERSION }} + # Do not set cache: here. setup-node cache hard-fails when the + # matching lockfile is absent. + + - name: Install dependencies + run: | + set -euo pipefail + case "${PACKAGE_MANAGER}" in + npm) if [ -f package-lock.json ]; then npm ci; else npm install; fi ;; + pnpm) corepack enable && (if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; else pnpm install; fi) ;; + yarn) corepack enable && (if [ -f yarn.lock ]; then yarn install --frozen-lockfile; else yarn install; fi) ;; + *) echo "::error::unknown PACKAGE_MANAGER ${PACKAGE_MANAGER}" && exit 1 ;; + esac + + - name: tsc --noEmit + if: env.HAS_TYPESCRIPT == 'true' + run: | + set -euo pipefail + if [ -f tsconfig.json ]; then + npx --yes tsc --noEmit -p tsconfig.json + else + echo "::notice::no tsconfig.json found, skipping type check" + fi + + test: + name: Node Test Suite + needs: detect-node + if: needs.detect-node.outputs.has_package == 'true' + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin "https://github.com/${REPOSITORY}.git" + auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 | tr -d '\n')" + git -c protocol.version=2 \ + -c "http.https://github.com/.extraheader=${auth_header}" \ + fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + + - name: Set up Node + uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0 + with: + node-version: ${{ env.NODE_VERSION }} + + - name: Install dependencies + run: | + set -euo pipefail + case "${PACKAGE_MANAGER}" in + npm) if [ -f package-lock.json ]; then npm ci; else npm install; fi ;; + pnpm) corepack enable && (if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; else pnpm install; fi) ;; + yarn) corepack enable && (if [ -f yarn.lock ]; then yarn install --frozen-lockfile; else yarn install; fi) ;; + *) echo "::error::unknown PACKAGE_MANAGER ${PACKAGE_MANAGER}" && exit 1 ;; + esac + + - name: Run test suite + env: + CI: "true" + run: | + set -euo pipefail + if [ -f package.json ] && node -e "process.exit(require('./package.json').scripts && require('./package.json').scripts.test ? 0 : 1)" 2>/dev/null; then + ${PACKAGE_MANAGER} test + else + echo "::notice::no test script defined in package.json, skipping" + fi diff --git a/.github/workflows/l9-lint-test.yml b/.github/workflows/l9-lint-test.yml new file mode 100644 index 0000000..081c858 --- /dev/null +++ b/.github/workflows/l9-lint-test.yml @@ -0,0 +1,217 @@ +# L9 consumer lint + test workflow (TEMPLATE โ€” copy into your repo) +# +# This file is NOT executed from l9-ci-core. Copy it into the CONSUMER +# repository at `.github/workflows/l9-lint-test.yml`. It replaces the +# lint / type-check / test half of the retired v1 `pr-pipeline.yml`. +# +# Org-seed safety (mirrors Node #58): +# - Lint / test run only when `pyproject.toml` or `requirements.txt` exists. +# - The test job is named `Python Test Suite`, not `Test Suite`, so it +# cannot collide with a required Node check context. +# - Toolchain versions come only from install-consumer-ci: no unpinned +# pytest plugin fallbacks. That action pins ruff, mypy and pytest and +# nothing else, so the pytest invocation below stays inside that set -- +# see Core's own pr-pipeline.yml, which runs a bare `pytest -q`. +# - The consumer's own package and dependencies are still installed from +# pyproject.toml / requirements.txt in BOTH jobs: pytest fails on import +# without them, and mypy silently type-checks a different world without +# them (an optional-dependency fallback guarded by `type: ignore` reads +# as an unused ignore once the real import is missing). +# +# v2 conventions preserved here: +# - immutable event-revision checkout (no floating action ref) +# - external actions pinned to full commit SHAs +# - explicit least-privilege permissions (contents: read, no write scopes) +name: L9 Lint and Test + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +# โ”€โ”€ Consumer config โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +# The org seeder rewrites this file from its own copy and force-updates the +# seed branch, so an edit made here is reverted by the next sync. Values that +# have to differ per repo are therefore auto-detected below; set one +# explicitly only if the detection is wrong for your layout. +env: + PYTHON_VERSION: "3.12" + # Blank = auto-detect: `src` when a src/ directory exists, else the repo + # root. A literal "." made mypy walk the entire checkout -- vendored packs, + # docs fixtures and all -- in every src-layout repo. + SOURCE_DIR: "" + TEST_DIR: "tests/" + # Fail the build below this line coverage percentage. 0 = advisory (no gate). + COVERAGE_THRESHOLD: "0" + +permissions: + contents: read + +concurrency: + group: l9-lint-test-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + detect-python: + name: Detect Python package + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + outputs: + has_python: ${{ steps.detect.outputs.has_python }} + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin "https://github.com/${REPOSITORY}.git" + auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 | tr -d '\n')" + git -c protocol.version=2 \ + -c "http.https://github.com/.extraheader=${auth_header}" \ + fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + - id: detect + name: Detect pyproject.toml or requirements.txt + run: | + set -euo pipefail + if [ -f pyproject.toml ] || [ -f requirements.txt ]; then + echo "has_python=true" >> "$GITHUB_OUTPUT" + else + echo "has_python=false" >> "$GITHUB_OUTPUT" + echo "::notice::no Python manifest; skipping lint and Python Test Suite" + fi + + lint: + name: Lint and Type Check + needs: detect-python + if: needs.detect-python.outputs.has_python == 'true' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin \ + "https://x-access-token:${TOKEN}@github.com/${REPOSITORY}.git" + git -c protocol.version=2 fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + git remote set-url origin "https://github.com/${REPOSITORY}.git" + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + with: + python-version: ${{ env.PYTHON_VERSION }} + - name: Install consumer package and dependencies + run: | + set -euo pipefail + if [ -f pyproject.toml ]; then + pip install -e ".[dev]" || pip install -e . || \ + echo "::notice::pyproject.toml is not pip-installable; relying on PYTHONPATH" + elif [ -f requirements.txt ]; then + pip install -r requirements.txt + fi + - name: Install extra CI requirements + run: | + set -euo pipefail + if [ -f requirements-ci.txt ]; then pip install -r requirements-ci.txt; fi + - name: Install consumer CI toolchain + uses: Quantum-L9/l9-ci-core/.github/actions/install-consumer-ci@7148fc73dcbf41367f5c5401432dc997b1f4f869 # main@7148fc7 + - id: srcdir + name: Resolve source directory + run: | + set -euo pipefail + dir="${SOURCE_DIR:-}" + if [ -z "${dir}" ]; then + if [ -d src ]; then dir="src"; else dir="."; fi + fi + echo "dir=${dir}" >> "$GITHUB_OUTPUT" + echo "::notice::SOURCE_DIR resolved to ${dir}" + - name: ruff check + run: ruff check . --output-format=github + - name: ruff format --check + run: ruff format --check . + - name: mypy + env: + SOURCE_DIR: ${{ steps.srcdir.outputs.dir }} + run: | + mypy "${SOURCE_DIR}" \ + --show-error-codes --pretty \ + --install-types --non-interactive --ignore-missing-imports + + test: + name: Python Test Suite + needs: detect-python + if: needs.detect-python.outputs.has_python == 'true' + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + steps: + - name: Checkout immutable event revision + env: + REPOSITORY: ${{ github.repository }} + REVISION: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git init . + git remote add origin \ + "https://x-access-token:${TOKEN}@github.com/${REPOSITORY}.git" + git -c protocol.version=2 fetch --depth=1 origin "${REVISION}" + git checkout --detach FETCH_HEAD + git remote set-url origin "https://github.com/${REPOSITORY}.git" + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + with: + python-version: ${{ env.PYTHON_VERSION }} + - name: Install consumer package and dependencies + run: | + set -euo pipefail + if [ -f pyproject.toml ]; then + pip install -e ".[dev]" || pip install -e . || \ + echo "::notice::pyproject.toml is not pip-installable; relying on PYTHONPATH" + elif [ -f requirements.txt ]; then + pip install -r requirements.txt + fi + - name: Install extra CI requirements + run: | + set -euo pipefail + if [ -f requirements-ci.txt ]; then pip install -r requirements-ci.txt; fi + # Core pins land last so a consumer dev extra declaring its own pytest + # range cannot move the version this job was pinned to. + - name: Install consumer CI toolchain + uses: Quantum-L9/l9-ci-core/.github/actions/install-consumer-ci@7148fc73dcbf41367f5c5401432dc997b1f4f869 # main@7148fc7 + - id: srcdir + name: Resolve source directory + run: | + set -euo pipefail + dir="${SOURCE_DIR:-}" + if [ -z "${dir}" ]; then + if [ -d src ]; then dir="src"; else dir="."; fi + fi + echo "dir=${dir}" >> "$GITHUB_OUTPUT" + echo "::notice::SOURCE_DIR resolved to ${dir}" + - name: pytest with coverage + env: + TESTING: "true" + SOURCE_DIR: ${{ steps.srcdir.outputs.dir }} + run: | + set -euo pipefail + PYTHONPATH=. pytest "${TEST_DIR}" \ + --cov="${SOURCE_DIR}" \ + --cov-report=xml --cov-report=term-missing \ + --cov-fail-under="${COVERAGE_THRESHOLD}" \ + --tb=short -v diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..af34433 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,10 @@ +{ + "recommendations": [ + "biomejs.biome", + "charliermarsh.ruff" + ], + "unwantedRecommendations": [ + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode" + ] +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..af40da1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,60 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in the Quantum-L9 community +a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, +ethnicity, sex characteristics, gender identity and expression, level of experience, education, +socioeconomic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +The Quantum-L9 platform team (`@Quantum-L9/platform`) is responsible for clarifying and enforcing this Code of Conduct. +They will take appropriate and fair corrective action in response to any behavior deemed inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all community spaces and also applies when an individual is officially +representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior: + +- Open [`gov-violation.yml`](.github/ISSUE_TEMPLATE/gov-violation.yml) for a public, routable report. +- Use this repository's Security Advisory form for a confidential / reporter-privacy path (see SECURITY.md). + +Do not "mention @platform" in markdown as the enforcement action. The resolvable owner is the CODEOWNERS team `@Quantum-L9/platform` on `.github/`, `SECURITY.md`, and `CODEOWNERS` only. + +All complaints will be reviewed and investigated promptly and fairly. + +## Enforcement Guidelines + +**1. Correction** โ€” Private written warning, clarity on violation, request for public apology. +**2. Warning** โ€” Warning with consequences for continued behavior; no interaction with involved parties for a specified period. +**3. Temporary Ban** โ€” Temporary ban from community interaction. +**4. Permanent Ban** โ€” Permanent ban for sustained, severe, or repeated violations. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..be61af5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to Quantum-L9 + +## Live activation (do this once per machine) + +Governance loads automatically. Do **not** clone Cursor-Governance into a +consumer workspace root, and do **not** create whole-directory Cursor +rules, skills, or commands symlinks โ€” that is the retired v2 ritual and +it creates a second governance tree. + +What actually wires: + +1. **sessionStart** โ€” `ops/hooks/session_start_bootstrap.sh` activates the + GitHub tip at `$HOME/.cursor-governance` (fast-forward or clone+swap). +2. **`l9-governance` plugin** โ€” `~/.cursor/plugins/local/l9-governance` โ†’ + the governance clone. Cursor discovers `rules/`, `skills/`, and + `commands/` under the plugin root. +3. **`.cursor-commands`** โ€” consumers only: a symlink to + `$HOME/.cursor-governance`. The SSOT clone must never self-alias. + +If a consumer workspace is missing those links: + +```bash +bash "$HOME/.cursor-governance/ops/scripts/ensure_workspace_wired.sh" "$(pwd)" +``` + +Read [CANONICAL_LAW.md](https://github.com/Quantum-L9/Cursor-Governance/blob/main/CANONICAL_LAW.md) +for the symlink contract and anti-patterns. + +## How an agent ships + +1. Local commits on a feature branch (L4 local autonomy). +2. Run `kernels/Recursive Alignment.md` then `kernels/Validate & Repair.md`. +3. Publish **only** with: + +```bash +PR_REMEDIATE=0 make pr +``` + +Do **not** `git push`, `gh pr create`, or `gh pr edit` to reach GitHub. +`make pr` runs the checkers; the alternatives skip them. + +Campaign PRs set `PR_BASE=origin/campaign/` and never target +`main`. Merge is a separate `/l9-pr-remediation` (Converge) step โ€” opening +a PR is not merge authorization. + +## CI gates + +Consumer CI is the org `l9-ci-pack` (missing-only seed): + +| Gate | When it runs | +| --- | --- | +| Biome | Always (JS/TS/JSON). Idle and green when the tree has no matching files. | +| Python lint + `Python Test Suite` | Only when `pyproject.toml` or `requirements.txt` exists. | +| Node typecheck + `Node Test Suite` | Only when a root `package.json` exists. | +| L9 Analysis | Semgrep + SDK publish. Fails with `governance-pack-missing` if `.github/governance/` is absent. | +| Governance caller | PR body / issue triage via `governance.yml@v1`. | + +Do not invent a second `biome.json` or a competing `ci.yml`. Extra Biome +excludes append to `files.includes` only. + +## Branch naming and commits + +- Branches: `feat/`, `fix/`, `chore/`, `docs/` +- Commits: Conventional Commits โ€” `feat(scope): message` +- Blast-radius paths (`.github/`, `infra/`, `SECURITY.md`, `CODEOWNERS`) + require the CODEOWNERS team plus the extra reviewer on those paths only. + +## Kernel authoring (l9-ci-core contributors only) + +- Kernels must use `on: workflow_call` only. +- Never reference `@main` from thin callers. +- See [workflow-interface-registry.yml](https://github.com/Quantum-L9/.github/blob/main/workflow-interface-registry.yml). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..dfdf60a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,73 @@ +--- +severity_sla: + critical: { cvss: "9.0-10.0", acknowledge: "24h", patch_target: "7d" } + high: { cvss: "7.0-8.9", acknowledge: "48h", patch_target: "14d" } + medium: { cvss: "4.0-6.9", acknowledge: "48h", patch_target: "30d" } + low: { cvss: "0.1-3.9", acknowledge: "5 business days", patch_target: "next release" } +routing: + vulnerability: security-advisory + conduct: CODE_OF_CONDUCT.md + ci_seed_failure: ci-failure.yml +--- + +# Security Policy + +## Scope + +This policy applies to **this repository**. The seeder writes one +`SECURITY.md` per consumer; do not keep a second competing file. A local +copy replaces org inheritance entirely โ€” there is no merge. + +## Out of Scope + +Vulnerabilities requiring physical access, social engineering of maintainers, or +issues in third-party dependencies without a demonstrated exploit path against +this repository โ€” report those upstream instead. + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Report privately via [this repository's Security Advisory form](https://github.com/Quantum-L9/l9-codegraph/security/advisories/new). +The org seeder rewrites that URL to `$GITHUB_REPOSITORY/security/advisories/new` +for the consumer being seeded. `ISSUE_TEMPLATE/config.yml` `contact_links` use +the same URL. + +Conduct reports go to `CODE_OF_CONDUCT.md` / `gov-violation.yml`. CI seed +failures go to `ci-failure.yml` or `seed-ci-failure.yml`. + +Include: + +- Affected repository and version/SHA +- Vulnerability type and CVSS score estimate (see guidance below) +- Reproduction steps (minimal reproducer preferred) +- Potential impact assessment +- Any proposed mitigations + +## Response SLA + +| Severity | Acknowledge | Patch Target | +| ------------------------ | --------------- | ------------------ | +| Critical (CVSS 9.0โ€“10.0) | 24 hours | 7 days | +| High (CVSS 7.0โ€“8.9) | 48 hours | 14 days | +| Medium (CVSS 4.0โ€“6.9) | 48 hours | 30 days | +| Low (CVSS 0.1โ€“3.9) | 5 business days | Next release cycle | + +## CVSS Scoring Guidance for Reporters + +Use [CVSS v3.1 Calculator](https://www.first.org/cvss/calculator/3.1) to estimate severity. +Key vectors: Attack Vector, Attack Complexity, Privileges Required, User Interaction, Scope, CIA Impact. + +## Automated Security Controls + +All repositories use: + +- **gitleaks** โ€” secret scanning on every commit +- **Semgrep** โ€” SAST via `l9-analysis.yml` (stack-selected rulesets) +- **Dependabot** โ€” github-actions SHA-pin freshness (no pip/npm unless added) +- **OpenSSF Scorecard** โ€” supply-chain security posture scoring where enabled + +## Disclosure Policy + +Quantum-L9 follows coordinated disclosure. We request 90 days to remediate before public disclosure. +After the patch is released, we will publish a GitHub Security Advisory crediting the reporter (unless anonymity is requested). diff --git a/biome.json b/biome.json new file mode 100644 index 0000000..b1fe395 --- /dev/null +++ b/biome.json @@ -0,0 +1,169 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json", + "root": true, + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true, + "defaultBranch": "main" + }, + "files": { + "ignoreUnknown": true, + "maxSize": 1048576, + "includes": [ + "**", + "!**/*.jsonc", + "!**/node_modules", + "!**/.venv", + "!**/venv", + "!**/__pycache__", + "!**/.git", + "!**/.ruff_cache", + "!**/.l9", + "!**/dist", + "!**/coverage", + "!**/package-lock.json", + "!**/npm-shrinkwrap.json" + ] + }, + "formatter": { + "enabled": true, + "formatWithErrors": false, + "useEditorconfig": true, + "indentStyle": "space", + "indentWidth": 2, + "lineEnding": "lf", + "lineWidth": 100, + "trailingNewline": true, + "bracketSpacing": true, + "bracketSameLine": false, + "attributePosition": "auto", + "expand": "auto", + "delimiterSpacing": false + }, + "linter": { + "enabled": true, + "rules": { + "preset": "recommended" + } + }, + "assist": { + "enabled": true, + "actions": { + "preset": "recommended", + "source": { + "organizeImports": "on", + "useSortedKeys": "off", + "useSortedAttributes": "off", + "useSortedInterfaceMembers": "off", + "useSortedEnumMembers": "on", + "useSortedPackageJson": "on", + "noDuplicateClasses": "on" + } + } + }, + "json": { + "parser": { + "allowComments": false, + "allowTrailingCommas": false + }, + "formatter": { + "enabled": true, + "indentStyle": "space", + "indentWidth": 2, + "lineEnding": "lf", + "lineWidth": 100, + "trailingNewline": true, + "trailingCommas": "none", + "bracketSpacing": true, + "expand": "auto", + "delimiterSpacing": false + }, + "linter": { + "enabled": true + }, + "assist": { + "enabled": false + } + }, + "javascript": { + "jsxRuntime": "transparent", + "formatter": { + "enabled": true, + "indentStyle": "space", + "indentWidth": 2, + "lineEnding": "lf", + "lineWidth": 100, + "trailingNewline": true, + "quoteStyle": "double", + "jsxQuoteStyle": "double", + "quoteProperties": "asNeeded", + "trailingCommas": "all", + "semicolons": "always", + "arrowParentheses": "always", + "bracketSpacing": true, + "bracketSameLine": false, + "attributePosition": "auto", + "operatorLinebreak": "after", + "expand": "auto", + "delimiterSpacing": false + }, + "linter": { + "enabled": true + }, + "assist": { + "enabled": true + } + }, + "css": { + "formatter": { + "enabled": false + }, + "linter": { + "enabled": false + }, + "assist": { + "enabled": false + } + }, + "graphql": { + "formatter": { + "enabled": false + }, + "linter": { + "enabled": false + }, + "assist": { + "enabled": false + } + }, + "html": { + "experimentalFullSupportEnabled": false, + "formatter": { + "enabled": false + }, + "linter": { + "enabled": false + }, + "assist": { + "enabled": false + } + }, + "overrides": [ + { + "includes": ["**/*.jsonc", "**/.vscode"], + "json": { + "parser": { + "allowComments": true, + "allowTrailingCommas": true + }, + "formatter": { + "enabled": false + }, + "linter": { + "enabled": false + } + } + } + ] +}