yehyakin · yehyakin · Aug 11, 2026 · Aug 11, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,88 @@
+name: Bug report
+description: Report a reproducible defect in Codex Sol Control
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a defect. Search existing issues first and remove credentials, private paths, and private repository content. Security-sensitive reports must use private vulnerability reporting.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight
+      options:
+        - label: I searched existing issues and reproduced this on the latest release or current main.
+          required: true
+        - label: This report contains no secrets or private project data.
+          required: true
+        - label: This is not a security vulnerability.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      description: Provide the release tag or commit SHA you tested.
+      placeholder: v0.4.1
+    validations:
+      required: true
+  - type: dropdown
+    id: operating-system
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: codex-surface
+    attributes:
+      label: Codex surface and version
+      description: For example, Codex CLI or Codex Desktop and its version.
+    validations:
+      required: true
+  - type: dropdown
+    id: installation
+    attributes:
+      label: Installation method
+      options:
+        - install.sh
+        - install.ps1
+        - Repository checkout only
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      placeholder: |
+        1. Run ...
+        2. Invoke ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Redacted evidence
+      description: Include exact commands, exit codes, or logs after removing sensitive data.
+      render: shell
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/yehyakin/codex-sol-control/security/advisories/new
+    about: Report suspected vulnerabilities privately. Do not open a public issue.
+  - name: Support guide
+    url: https://github.com/yehyakin/codex-sol-control/blob/main/SUPPORT.md
+    about: Check supported versions, environments, and the correct help channel.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,60 @@
+name: Feature request
+description: Propose a focused improvement to Codex Sol Control
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the user problem before the implementation. Proposals should preserve the single-controller architecture and avoid adding roles without clear evidence.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Preflight
+      options:
+        - label: I searched existing issues and pull requests for this proposal.
+          required: true
+        - label: This request is about Codex Sol Control rather than a downstream business project.
+          required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What concrete limitation or repeated failure are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe observable acceptance criteria.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Keep this focused; implementation details are optional.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: true
+  - type: textarea
+    id: routing-impact
+    attributes:
+      label: Routing and safety impact
+      description: Note effects on Sol control, worker selection, permissions, write ownership, evidence, or fail-closed behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope boundaries
+      description: State what this proposal intentionally does not change.
+    validations:
+      required: true
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,26 @@
+## Summary
+
+Describe the user-visible change.
+
+## Why
+
+Explain the problem and why this is the smallest sufficient change.
+
+## Scope
+
+- Changed:
+- Intentionally unchanged:
+
+## Validation and evidence
+
+List exact commands, exit codes, and relevant runtime evidence. Distinguish local verification, hosted CI, installed state, and model/runtime observations.
+
+## Checklist
+
+- [ ] The change is focused and does not include unrelated refactors.
+- [ ] Relevant contract or forward tests were added or updated.
+- [ ] `README.md` and `README.en.md` remain aligned when shared facts changed.
+- [ ] No credentials, private paths, or private repository data are included.
+- [ ] Permission, write-ownership, exact-routing, and fail-closed boundaries are preserved.
+- [ ] Claims are supported by fresh evidence and known limitations are explicit.
+- [ ] Documentation and licensing attribution are complete.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,52 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project 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 include:
+
+- demonstrating empathy and kindness toward other people;
+- respecting differing opinions, viewpoints, and experiences;
+- giving and gracefully accepting constructive feedback;
+- accepting responsibility, apologizing to those affected by mistakes, and learning from the experience;
+- focusing on what is best for the community and the project.
+
+Examples of unacceptable behavior include:
+
+- sexualized language or imagery, sexual attention, or advances of any kind;
+- trolling, insulting or derogatory comments, and personal or political attacks;
+- public or private harassment;
+- publishing another person's private information without explicit permission;
+- other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement responsibilities
+
+Project maintainers are responsible for clarifying and enforcing these standards. They may remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies in all project spaces and when an individual officially represents the project in public spaces.
+
+## Reporting and enforcement
+
+Report abusive, harassing, or otherwise unacceptable behavior privately through the repository's [private vulnerability reporting form](https://github.com/yehyakin/codex-sol-control/security/advisories/new). Begin the report title with `Code of Conduct:` so it can be routed correctly. Do not include another person's private information in a public issue.
+
+Maintainers will review reports promptly, respect the privacy and safety of reporters, and apply consequences proportionate to the nature, impact, and persistence of the behavior. A maintainer who does not follow or enforce this Code of Conduct may be removed from the project team.
+
+## Enforcement guidelines
+
+Maintainers will use these guidelines when deciding consequences:
+
+1. **Correction** — a private warning and explanation for inappropriate language or behavior with limited community impact.
+2. **Warning** — a warning with consequences for continued behavior when an incident or pattern has affected community members.
+3. **Temporary ban** — a time-limited ban from project interaction for a serious or sustained violation.
+4. **Permanent ban** — permanent removal for repeated violations, harassment, aggression, or other conduct harmful to the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing to Codex Sol Control
+
+Thank you for helping improve Codex Sol Control. Contributions should keep the project focused on one job: Sol controls planning, delegation, and review while bounded workers execute independently verifiable work.
+
+## Before you start
+
+- Search existing issues and pull requests before opening a new one.
+- Use the bug or feature issue form for reproducible defects and proposals.
+- Open an issue before a material routing, security, installer, or compatibility change.
+- Use GitHub's [private vulnerability reporting](https://github.com/yehyakin/codex-sol-control/security/advisories/new) for security-sensitive reports. Do not disclose them in a public issue.
+
+## Development setup
+
+The repository requires Python 3.11 or newer. On macOS or Linux, run:
+
+```sh
+bash scripts/validate.sh
+bash scripts/test.sh
+bash scripts/install.sh --check
+```
+
+On Windows, validate from PowerShell 5.1 or PowerShell 7:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/validate.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File tests/windows-lifecycle.ps1
+```
+
+Use `pwsh` in place of `powershell` to exercise PowerShell 7.
+
+## Pull requests
+
+Keep each pull request focused and explain both the user-visible change and its evidence. A pull request should:
+
+- preserve user changes, permission boundaries, exact model routing, and fail-closed behavior;
+- add or update the smallest relevant contract or forward test;
+- keep `README.md` and `README.en.md` aligned when shared facts change;
+- distinguish local tests, hosted CI, installed state, and runtime evidence;
+- contain no credentials, private paths, private repository data, or generated test residue;
+- avoid unrelated refactors, new roles, or duplicated implementations.
+
+Configure a verified GitHub email or GitHub-provided noreply email before committing so GitHub can attribute future work correctly.
+
+By submitting a contribution, you agree that it may be licensed under the repository's [Apache License 2.0](LICENSE).
diff --git a/README.en.md b/README.en.md
@@ -399,6 +399,14 @@ README.en.md                   English
 - [Real-project routing samples](tests/real-project-benchmark.md)
 - [v0.4.0 implementation report](SOL_CONTROL_IMPLEMENTATION_REPORT.md)
 
+## Maintainer and support
+
+Primary maintainer: [@yehyakin](https://github.com/yehyakin). The project supports the latest tagged release and current `main`; see [SUPPORT.md](SUPPORT.md) for environment boundaries and help channels. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing, and use the structured [issue templates](https://github.com/yehyakin/codex-sol-control/issues/new/choose) for reproducible repository defects.
+
+## Security
+
+Do not open a public issue for security-sensitive behavior or attach tokens, private paths, or private repository content. Read [SECURITY.md](SECURITY.md) and submit a [private vulnerability report](https://github.com/yehyakin/codex-sol-control/security/advisories/new).
+
 ## Development and testing
 
 Python 3.11 or newer is required.

diff --git a/README.md b/README.md
@@ -399,6 +399,14 @@ README.en.md                   English
 - [真实项目路由样本](tests/real-project-benchmark.md)
 - [v0.4.0 实施报告](SOL_CONTROL_IMPLEMENTATION_REPORT.md)
 
+## 维护与支持
+
+主要维护者：[@yehyakin](https://github.com/yehyakin)。项目支持最新发布版本与当前 `main`；具体环境边界和求助渠道见 [SUPPORT.md](SUPPORT.md)。提交改进前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)，可复现问题请使用仓库的结构化 [Issue 模板](https://github.com/yehyakin/codex-sol-control/issues/new/choose)。
+
+## 安全
+
+安全问题不要提交公开 Issue，也不要附带 Token、私有路径或私有仓库内容。请阅读 [SECURITY.md](SECURITY.md)，并通过 GitHub [私密漏洞报告](https://github.com/yehyakin/codex-sol-control/security/advisories/new)提交。
+
 ## 开发与测试
 
 需要 Python 3.11 或更高版本。

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target the latest tagged release and the current `main` branch.
+
+| Version | Supported |
+| --- | --- |
+| `0.4.x` | Yes |
+| `< 0.4` | No |
+
+## Reporting a vulnerability
+
+Report suspected vulnerabilities through GitHub's [private vulnerability reporting](https://github.com/yehyakin/codex-sol-control/security/advisories/new). Do not open a public issue and do not include credentials, tokens, private paths, or private repository content.
+
+Include the affected version or commit, operating system and Codex surface, reproduction steps, impact, and a minimally redacted proof of concept when safe. We aim to acknowledge a report within seven days and will share the next update after triage.
+
+## Security scope
+
+Reports are in scope when they concern:
+
+- installer, uninstaller, validation, backup, checksum, path, or rollback behavior;
+- unexpected writes, scope violations, permission escalation, or unsafe agent routing;
+- exposure of secrets or private repository data caused by this repository;
+- bypasses of the documented review, evidence, or fail-closed boundaries.
+
+The following belong elsewhere:
+
+- vulnerabilities in OpenAI, Codex, GitHub, an operating system, or another third-party service;
+- model availability, model quality, latency, pricing, or cost-estimate disagreements;
+- bugs in downstream business projects that do not originate in this repository.
+
+Please report third-party product vulnerabilities to the affected vendor.
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -0,0 +1,15 @@
+# Support
+
+Codex Sol Control is maintained for the latest tagged release and the current `main` branch. The supported installation surfaces are macOS and Linux through the POSIX lifecycle scripts, plus Windows through Windows PowerShell 5.1 and PowerShell 7.
+
+Exact custom-agent selection, models, reasoning effort, permissions, and nested delegation depend on the Codex host. The repository documents only runtime surfaces for which evidence has been recorded; GitHub-hosted Windows validation is not proof of every physical Windows or Codex Desktop configuration.
+
+## Where to ask
+
+- Reproducible repository defect: use the [bug report form](https://github.com/yehyakin/codex-sol-control/issues/new?template=bug_report.yml).
+- Focused improvement proposal: use the [feature request form](https://github.com/yehyakin/codex-sol-control/issues/new?template=feature_request.yml).
+- Security-sensitive behavior: follow the [security policy](SECURITY.md) and report it privately.
+- Contribution workflow: read [CONTRIBUTING.md](CONTRIBUTING.md).
+- OpenAI account, billing, product availability, or Codex service issue: use official OpenAI support.
+
+Support does not include debugging unrelated downstream business repositories. Never attach secrets, unredacted configuration, private source code, or private filesystem paths to a public issue.