docs: document contribution and security workflows

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What does this PR change? -->
+
+## Why
+
+<!-- What problem does this solve, and why is this approach appropriate? -->
+
+## Validation
+
+<!-- List the commands and manual checks you ran. -->
+
+- [ ] `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
+
+<!-- Link an issue with "Closes #123", or write "None". -->

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: `<name>.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.

CONTRIBUTING.md

@@ -56,10 +56,14 @@ 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. 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
+   changes.
+6. Run the relevant checks before opening the PR:
 
 ```sh
 bun run typecheck
@@ -72,6 +76,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 +179,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 suspected vulnerabilities, including secrets,
+authentication bypasses, or vulnerabilities that expose private workspaces.
+Follow the private reporting instructions in [SECURITY.md](./SECURITY.md).

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)

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.

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.