From 1f223cb4469fa1a5afe48ba46ee02546c3e16655 Mon Sep 17 00:00:00 2001 From: bo Date: Wed, 29 Jul 2026 10:24:57 +0800 Subject: [PATCH 1/3] docs: document contribution and security workflows --- .github/pull_request_template.md | 28 ++++++++++++++++++++++ AGENTS.md | 9 +++++++ CONTRIBUTING.md | 35 ++++++++++++++++++++++++---- README.md | 1 + SECURITY.md | 40 ++++++++++++++++++++++++++++++++ docs/security.md | 4 ++++ 6 files changed, 112 insertions(+), 5 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 SECURITY.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..0aa3d534 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ +## Summary + + + +## Why + + + +## Validation + + + +- [ ] `bun run typecheck` +- [ ] `bun run test` +- [ ] `bun run build` when the production package or Web UI is affected + +## Documentation and security + +- [ ] I updated user-facing documentation when behavior, setup, or + configuration changed. +- [ ] I added or updated tests for behavior changes. +- [ ] I did not commit credentials, tokens, private configuration, or generated + secrets. +- [ ] I described any security or trust-boundary impact above. + +## Related issue + + diff --git a/AGENTS.md b/AGENTS.md index 00a99196..64e73d36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -444,6 +444,15 @@ HTTP Streamable only. Built-in: context7, grep.app, exa (hardcoded in `BUILTIN_M - Test runner: `bun:test`. Import from `"bun:test"`. Use `mock()` not `jest.fn()`. Files: `.test.ts` colocated. Temp dirs: `__test_tmp__/` cleaned in `afterAll`. - Entry point: `apps/server/src/main.ts` boots the headless Hono server. `package.json` bin → `./apps/server/src/main.ts`. +## Repository GitHub Workflow + +- `main` is protected and accepts changes through pull requests only. Never commit or push directly to `main`. +- Start repository work from the latest `origin/main` on a focused feature branch. Keep branch creation, commit, push, PR creation, and merge as explicit, separately reported actions. +- Before opening a PR, run the relevant local validation documented in `CONTRIBUTING.md`. +- The required GitHub gates are the `Verify` status check and the CodeQL code-scanning policy. `Verify` installs with the frozen lockfile, typechecks, runs tests with diagnostics, builds the production binary, and smoke-tests that binary. +- CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. Address actionable findings and resolve every review conversation, but final merge judgment remains human. +- Merge PRs with squash merge only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change. + ## Testing Patterns - Mock LLM calls through `setLlmAdapterForTest()` from `packages/agent-core/src/llm`; do not reintroduce `__setStreamTextForTest`, `__setGenerateTextForTest`, or public `llmObject()` aliases. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7df1185..3f9bceaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,10 +56,13 @@ Validation order is `typecheck` before `test`. ## Pull request workflow 1. Open an issue or describe the problem clearly in the PR. -2. Keep changes focused. Separate unrelated refactors from feature work. -3. Add or update tests for behavior changes. -4. Update user-facing documentation when behavior, setup, or configuration changes. -5. Run the relevant checks before opening the PR: +2. Create a focused branch from the latest `main`. Contributors without write + access should work from a fork. +3. Keep changes focused. Separate unrelated refactors from feature work. +4. Add or update tests for behavior changes. +5. Update user-facing documentation when behavior, setup, or configuration + changes. +6. Run the relevant checks before opening the PR: ```sh bun run typecheck @@ -72,6 +75,26 @@ For changes that affect the production package or Web UI, also run: bun run build ``` +Open a ready PR against `main` and complete the PR template. Direct pushes to +`main`, force pushes, and deletion of `main` are blocked by the repository +ruleset. + +Every PR must satisfy the following repository gates: + +- `Verify` must pass. It installs dependencies with the frozen lockfile, + typechecks the monorepo, runs tests with diagnostics, builds the production + binary, and smoke-tests that binary. +- The CodeQL code-scanning policy must pass. +- Every review conversation must be resolved. + +CodeRabbit and Cubic automatically provide advisory AI reviews on ready PRs. +They may add incremental feedback after new commits are pushed. Address +actionable findings, explain intentional decisions when appropriate, and do not +treat an AI approval as a substitute for maintainer judgment. + +Maintainers merge accepted PRs with squash merge. The merged PR becomes one +commit on `main`, and GitHub deletes the merged head branch automatically. + ## Code conventions - TypeScript is strict. Do not suppress type errors with `as any`, `@ts-ignore`, or `@ts-expect-error`. @@ -155,4 +178,6 @@ guesses or automatically selects models. ## Reporting security issues -Do not open public issues for secrets, authentication bypasses, or vulnerabilities that expose private workspaces. Contact the maintainer privately until a security policy is published. +Do not open public issues for secrets, authentication bypasses, or +vulnerabilities that expose private workspaces. Follow the private reporting +instructions in [SECURITY.md](./SECURITY.md). diff --git a/README.md b/README.md index 510685b7..458929fd 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,7 @@ ArchCode outside a trusted machine or network. - [Workbench concepts](docs/concepts.md) - [GitHub and MCP integrations](docs/integrations.md) - [Security and trust boundaries](docs/security.md) +- [Security vulnerability reporting](SECURITY.md) - [Architecture](docs/architecture.md) - [Contributing](CONTRIBUTING.md) - [Changelog](CHANGELOG.md) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..0d79ec5c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security policy + +## Supported versions + +Security reports are accepted for the latest ArchCode release and the current +`main` branch. Older releases may no longer receive a patch; maintainers will +identify the affected and fixed versions when coordinating a report. + +## Reporting a vulnerability + +Do not disclose suspected vulnerabilities, credentials, authentication +bypasses, or private-workspace exposure in a public issue or pull request. + +Use GitHub's private vulnerability reporting flow: + +1. Open the repository's **Security and quality** tab. +2. Open **Advisories**. +3. Select **Report a vulnerability**. + +Include enough information for maintainers to reproduce and assess the issue: + +- affected version, commit, or component; +- security impact and realistic attack conditions; +- reproduction steps or a minimal proof of concept; +- relevant logs with secrets and personal data removed; +- any known workaround or suggested fix; +- whether and where the issue has already been disclosed. + +If the private reporting button is unavailable, open a public issue containing +no vulnerability details and ask the maintainer for a private contact channel. + +If a real credential has been exposed, revoke or rotate it immediately before +submitting the report. + +## Coordinated disclosure + +Maintainers will acknowledge the report as soon as practical, investigate its +impact, and coordinate a fix and disclosure with the reporter. Do not publish +technical details before a fix or advisory is available unless the maintainers +and reporter agree on a disclosure timeline. diff --git a/docs/security.md b/docs/security.md index 57413289..27815d99 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,5 +1,9 @@ # Security and trust boundaries +To report a suspected vulnerability privately, follow the repository +[security policy](../SECURITY.md). This document describes product deployment +and trust boundaries rather than the vulnerability disclosure process. + ArchCode is a self-hosted coding Agent runtime with access to registered source workspaces. Treat the process as a powerful development tool, not as an untrusted public Web application. From 626888c6755b7bf629bf4f326c04e41d6be7ddd6 Mon Sep 17 00:00:00 2001 From: bo Date: Wed, 29 Jul 2026 10:49:02 +0800 Subject: [PATCH 2/3] docs: clarify contribution security guidance --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f9bceaa..43267c00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,8 +56,8 @@ Validation order is `typecheck` before `test`. ## Pull request workflow 1. Open an issue or describe the problem clearly in the PR. -2. Create a focused branch from the latest `main`. Contributors without write - access should work from a fork. +2. Fetch the latest `origin/main` and create a focused branch from it. + Contributors without write access should work from a fork. 3. Keep changes focused. Separate unrelated refactors from feature work. 4. Add or update tests for behavior changes. 5. Update user-facing documentation when behavior, setup, or configuration @@ -178,6 +178,6 @@ guesses or automatically selects models. ## Reporting security issues -Do not open public issues for secrets, authentication bypasses, or -vulnerabilities that expose private workspaces. Follow the private reporting -instructions in [SECURITY.md](./SECURITY.md). +Do not open public issues for suspected vulnerabilities, including secrets, +authentication bypasses, or vulnerabilities that expose private workspaces. +Follow the private reporting instructions in [SECURITY.md](./SECURITY.md). From 29b61b00069debf062b905d5fcb2d592dbffe129 Mon Sep 17 00:00:00 2001 From: bo Date: Wed, 29 Jul 2026 10:52:46 +0800 Subject: [PATCH 3/3] docs: clarify fork branch guidance --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43267c00..9ab777df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,8 +56,9 @@ Validation order is `typecheck` before `test`. ## Pull request workflow 1. Open an issue or describe the problem clearly in the PR. -2. Fetch the latest `origin/main` and create a focused branch from it. - Contributors without write access should work from a fork. +2. Fetch the latest `main` from the canonical repository and create a focused + branch from it. Use `origin/main` as a collaborator; when working from a + fork, synchronize it first and use the canonical `upstream/main`. 3. Keep changes focused. Separate unrelated refactors from feature work. 4. Add or update tests for behavior changes. 5. Update user-facing documentation when behavior, setup, or configuration