diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..0ffc6f4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,76 @@ +name: Bug report +description: Report a reproducible Loop Craft defect without exposing private source material. +title: "[Bug]: " +body: + - type: markdown + attributes: + value: | + Thank you for helping improve Loop Craft. For suspected security issues, stop here and use the private reporting link shown in the template chooser. + - type: dropdown + id: version + attributes: + label: Loop Craft version + options: + - v0.4.0 + - main + - Other commit or version + validations: + required: true + - type: dropdown + id: route + attributes: + label: Entry route + options: + - From scratch + - Existing Skill + - Conversation + - Direct Build + - Verify + validations: + required: true + - type: dropdown + id: adapter + attributes: + label: Selected Adapter + options: + - codex-skill + - compact-prompt + - Not reached or not applicable + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Use synthetic inputs and include the exact command or Agent request. + placeholder: Describe the smallest sequence that reproduces the problem. + 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: environment + attributes: + label: Environment + description: Operating system, Python version and Agent surface. + validations: + required: true + - type: checkboxes + id: redaction + attributes: + label: Evidence redaction + options: + - label: I removed secrets, personal data, raw private conversations, absolute local paths and unrelated Evidence. + required: true + - label: This is not a security vulnerability or an authority-boundary bypass. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..612410e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Private security report + url: https://github.com/Conradgui/loop-craft/security/advisories/new + about: Report vulnerabilities and authority-boundary bypasses without exposing sensitive material. + - name: Usage and product boundaries + url: https://github.com/Conradgui/loop-craft#readme + about: Check installation, routes, current capabilities and explicit limitations first. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..bfd68f7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,50 @@ +name: Feature request +description: Propose a bounded user capability, not infrastructure without a user path. +title: "[Feature]: " +body: + - type: textarea + id: user_problem + attributes: + label: User problem and value + description: What can a user not complete today, and who encounters the problem? + validations: + required: true + - type: textarea + id: current_alternative + attributes: + label: Current alternative + description: How is the task handled today, and why is that insufficient? + validations: + required: true + - type: dropdown + id: boundary + attributes: + label: Product boundary + options: + - Existing 0/1-Loop and Adapter behavior + - New entry or packaging behavior + - Runtime, multi-Loop, publishing or another currently unsupported area + - Unsure + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed outcome + description: Describe observable user behavior, not a preferred internal implementation. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence and examples + description: Provide sanitized examples, repeated failure patterns or prior attempts. + - type: checkboxes + id: scope + attributes: + label: Scope check + options: + - label: I checked the README boundaries and existing Issues before proposing this capability. + required: true + - label: I removed private conversations, credentials, personal data and unrelated Evidence. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..61ec560 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +## User impact + +What can a user do after this change that they could not do before? + +## Scope + +- Entry, Core, Adapter, Evidence or repository surface changed: +- Source and authority boundaries affected: +- Deliberately unchanged: + +## Validation + +- [ ] Targeted deterministic checks: +- [ ] Real build / verify when the build chain changed: +- [ ] Behavioral evaluation when shared Skill prose changed: +- [ ] Local paths, conversations, credentials and unrelated Evidence are absent from the diff: + +## Not run + +List checks deliberately not run and explain which concrete risk did not justify them. + +## Boundaries + +Document unsupported behavior, compatibility limitations and any follow-up that is intentionally +outside this Pull Request. diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index a5f9ed9..ea27c9d 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -2,7 +2,12 @@ name: Validate Loop Craft on: push: + branches: [main] pull_request: + workflow_dispatch: + +permissions: + contents: read jobs: validate: @@ -20,14 +25,15 @@ jobs: PYTHONUTF8: "1" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/checkout@v4 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: Conradgui/skill-creator-pro + ref: eb23656e56ea3555599a6c5278a8b5834dc56b6d path: .tmp/skill-creator-pro - - uses: actions/setup-python@v5 + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: ${{ matrix.python-version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 44bc799..8b4b0f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ Dual-output Adapter release. normalized result digests. - Adapter-neutral Artifact contracts and adapter-aware read-only verification for both Skill and Prompt drift. +- A stable `v0.4.0/loop-craft` installation path plus Security, Code of Conduct, structured + Issue Forms and a Pull Request contract for public collaboration. ### Changed @@ -28,14 +30,16 @@ Dual-output Adapter release. - Final staging promotion has a bounded retry for the observed transient Windows `PermissionError`; persistent permission failures still stop the build. - Version metadata is unified at `0.4.0`. +- GitHub Actions and the Skill Creator PRO validator source are pinned to immutable revisions; + the workflow can also be invoked manually as a release gate. ### Boundaries - Compact Prompt preserves the approved behavior, authority, verification, stopping and invariant content, but it does not supply tools, state, scheduling, or independent audit. - Source-preserving Existing Skill upgrades remain Codex Skill builds. Runtime, multi-Loop, - Override, Subloop, publishing, scheduling, installation automation, Release and Git tags - remain outside this version. + Override, Subloop, publishing, scheduling and installation automation remain outside this + version. ## 0.3.0 - 2026-07-31 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bb457bd --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,29 @@ +# Code of Conduct + +## Our standard + +Loop Craft welcomes people who participate in good faith, regardless of experience level or +background. Be respectful, focus criticism on ideas and observable evidence, explain unfamiliar +terms, and leave room for people to correct mistakes. + +Unacceptable behavior includes harassment, discrimination, personal attacks, threats, deliberate +misrepresentation of another person's work, publishing private information without permission, +or repeatedly disrupting a technical discussion after a maintainer has set a boundary. + +## Project scope + +This standard applies in the repository and in public spaces where someone is representing Loop +Craft. Technical disagreement is welcome. Maintainers may edit, remove or reject contributions +and may temporarily or permanently restrict participation when behavior is unsafe or persistently +disruptive. + +## Reporting and enforcement + +For an ordinary moderation concern, flag the relevant GitHub content or open a concise Issue. If +the report contains private or sensitive information, use the +[private reporting form](https://github.com/Conradgui/loop-craft/security/advisories/new) and begin +the title with `CODE OF CONDUCT`. + +Reports will be reviewed as privately as the selected GitHub channel permits. The maintainer will +consider context, impact, prior behavior and the safety of affected participants before choosing +a proportionate response. Retaliation against a good-faith reporter is not acceptable. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76874f0..c566a15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -127,3 +127,13 @@ the official Skill validator, link checking, a real build/verify, and a drift ne on Linux and Windows across Python 3.12 and 3.13. CI does not cover behavioral evaluation. If you touched prose, say so and attach results. + +## Security reports + +Do not open a public Issue for a suspected vulnerability, authority-boundary bypass, sensitive +Evidence leak or approval/stop-condition bypass. Follow [SECURITY.md](SECURITY.md) and use the +private GitHub reporting form. Public Bug reports must use synthetic or redacted inputs and must +not contain credentials, personal data, raw private conversations or unrelated local paths. + +Participation in Issues and Pull Requests is also governed by the +[Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 079fcf8..05b8d1a 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ > Workflow instead of manufacturing a fake Loop. [中文版](README.zh.md) · [Design](docs/DESIGN.md) · -[Evaluation](docs/REAL_WORLD_EVALUATION.md) · [Contributing](CONTRIBUTING.md) +[Evaluation](docs/REAL_WORLD_EVALUATION.md) · [Contributing](CONTRIBUTING.md) · +[Security](SECURITY.md) --- @@ -97,7 +98,7 @@ Ask Codex to use its Skill Installer: ```text Use $skill-installer to install the skill at -https://github.com/Conradgui/loop-craft/tree/main/loop-craft +https://github.com/Conradgui/loop-craft/tree/v0.4.0/loop-craft ``` Start a new Codex turn after installation so the Skill can be discovered. @@ -292,6 +293,14 @@ The exact source revisions, adopted mechanisms, exclusions, and ownership bounda recorded in the [resource registry](docs/references/resource-registry.yaml) and summarized in [NOTICE](NOTICE.md). +## Community + +Report reproducible defects through [Issues](https://github.com/Conradgui/loop-craft/issues) +and propose changes through [Pull Requests](https://github.com/Conradgui/loop-craft/pulls). +Read [Contributing](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before +participating. Suspected vulnerabilities and authority-boundary bypasses belong in the private +channel described by the [Security Policy](SECURITY.md), never in a public Issue. + ## License Loop Craft is distributed under the [Apache License 2.0](LICENSE). Independent reference diff --git a/README.zh.md b/README.zh.md index bbc92a3..0b04d4e 100644 --- a/README.zh.md +++ b/README.zh.md @@ -16,7 +16,8 @@ > “有 Loop”强行制造循环。 [English](README.md) · [架构设计](docs/DESIGN.md) · -[评估证据](docs/REAL_WORLD_EVALUATION.md) · [参与开发](CONTRIBUTING.md) +[评估证据](docs/REAL_WORLD_EVALUATION.md) · [参与开发](CONTRIBUTING.md) · +[安全策略](SECURITY.md) --- @@ -94,7 +95,7 @@ flowchart TB ```text 使用 $skill-installer 安装这个地址中的 Skill： -https://github.com/Conradgui/loop-craft/tree/main/loop-craft +https://github.com/Conradgui/loop-craft/tree/v0.4.0/loop-craft ``` 安装后开启一个新的 Codex 对话，让新 Skill 被重新发现。 @@ -266,6 +267,13 @@ Loop Craft 选择性地本地化了 Loopy、Workflow Skill Creator、Skill Polis 每个来源的固定 revision、采纳机制、排除内容和所有权边界记录在 [资源登记](docs/references/resource-registry.yaml)，摘要见 [NOTICE](NOTICE.md)。 +## 社区参与 + +可复现缺陷请提交到 [Issues](https://github.com/Conradgui/loop-craft/issues)，代码与文档改动请走 +[Pull Requests](https://github.com/Conradgui/loop-craft/pulls)。参与前请阅读[贡献指南](CONTRIBUTING.md) +和[行为准则](CODE_OF_CONDUCT.md)。疑似漏洞或权限边界绕过必须使用[安全策略](SECURITY.md)中的 +私密入口，不要公开到 Issue。 + ## 许可证 Loop Craft 按 [Apache License 2.0](LICENSE) 分发。独立参考项目继续适用各自的许可证与归属 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f5dba87 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ +# Security Policy + +## Supported versions + +Security fixes are considered for the current `0.4.x` line. Older development snapshots are +not supported. The repository may document later versions before a formal Release exists; the +[Releases page](https://github.com/Conradgui/loop-craft/releases) is the authoritative list of +published versions. + +## Report a vulnerability privately + +Do not open a public Issue for a suspected vulnerability. Use GitHub's +[private vulnerability reporting form](https://github.com/Conradgui/loop-craft/security/advisories/new) +and include: + +- the affected Loop Craft version or commit; +- the entry route and selected Adapter; +- the smallest safe reproduction; +- the expected and observed authority or data boundary; +- whether generated Artifact or Evidence content is involved; +- a suggested remediation, when available. + +Remove secrets, raw private conversations, credentials, personal data, absolute local paths and +unrelated Evidence before submitting. A synthetic reproduction is preferred. + +The maintainer will make a best-effort acknowledgement within seven days, assess severity and +coordinate disclosure through the private advisory. Remediation timing depends on impact and +available maintainer capacity; this is not a guaranteed service-level agreement. + +## Security boundary + +Loop Craft is a local Agent Skill and deterministic build chain. When explicitly approved, it +can read scoped source material, write a new local Artifact and Evidence Package, and execute +the selected local validator. It does not provide authentication, sandboxing, secrets storage, +remote execution, publishing or a Runtime permission system. + +A security report is appropriate when Loop Craft unexpectedly crosses an approved filesystem or +authority boundary, leaks excluded source material into an Artifact, accepts tampered Evidence, +weakens a stop/approval condition, or makes an unsupported compatibility claim. General feature +requests and ordinary classification disagreements belong in the public Issue tracker after all +sensitive material is removed. diff --git a/dashboard/status.json b/dashboard/status.json index ca19682..2565a08 100644 --- a/dashboard/status.json +++ b/dashboard/status.json @@ -1,23 +1,23 @@ { "project": "Loop Craft", - "updated_at": "2026-08-01T22:53:49-07:00", + "updated_at": "2026-08-01T23:33:59-07:00", "overall": { - "label": "PASS · 0.4.0 双输出闭环", - "tone": "ready", - "summary": "三个入口汇合到同一 Compiler 与 Final Execution IR；一次 build 可选择确定性 Codex Skill 或语义完整、runtime-delegated 的 Compact Prompt，并为所选 Artifact 生成独立 Evidence。Codex Skill 可绑定当前官方 Validator 的摘要收据。本地双产物 clean，main 与 GitHub 元数据已同步，run 30734873022 的 Ubuntu / Windows × Python 3.12 / 3.13 四项全部成功。Runtime 是独立执行产品，不是本轮缺失尾项。" + "label": "RELEASE CANDIDATE · v0.4.0 正式开源发布", + "tone": "progress", + "summary": "0.4.0 产品能力保持 PASS：三入口、Skill / Compact Prompt 双 Adapter、Evidence 与 verify 均已闭合。正式开源发布合同已在隔离分支补齐：稳定版本安装路径、不可变 CI 依赖、Security、Code of Conduct、Issue Forms 与 PR 模板已本地可用；PR CI、main CI、v0.4.0 Release、私密漏洞报告和 main 保护仍待远端真实裁决。" }, "milestone": { - "name": "M3 · 0.4.0 Skill / Prompt 双 Adapter", - "state": "complete", - "progress": 100, - "progress_label": "设计 1 / 1；实现 1 / 1；本地双产物 1 / 1；文档与看板 1 / 1；远端 CI 1 / 1", - "next": "0.4.0 已封板；后续新能力按独立产品决策重新进入 mainline，不把 Runtime 等边界外方向视为当前欠账" + "name": "M4 · v0.4.0 正式开源发布", + "state": "active", + "progress": 60, + "progress_label": "发布设计 1 / 1；仓库合同 1 / 1；本地出口 1 / 1；PR / main CI 0 / 1；Release / 保护 0 / 1", + "next": "推送 ready PR 并等待 PR / main 双阶段远端 CI，再从已验证 commit 创建 v0.4.0 Release 并保护 main" }, "metrics": [ { "label": "当前本地版本", - "value": "main · 0.4.0", - "tone": "ready" + "value": "codex/oss-release-readiness · 0.4.0", + "tone": "progress" }, { "label": "首次远端 CI", @@ -61,7 +61,7 @@ }, { "label": "0.4.0 本地候选验证", - "value": "190 passed · Skill / Prompt clean", + "value": "191 passed · Skill / Prompt clean", "tone": "ready" }, { @@ -71,8 +71,8 @@ }, { "label": "阶段出口", - "value": "PASS · local + remote", - "tone": "ready" + "value": "PRODUCT PASS · RELEASE PENDING", + "tone": "progress" }, { "label": "当前 Adapter 输出", @@ -83,6 +83,11 @@ "label": "Codex 原生兼容收据", "value": "Skill is valid! · digest-bound", "tone": "ready" + }, + { + "label": "正式开源仓库合同", + "value": "LOCAL PASS · remote pending", + "tone": "progress" } ], "handoff": { @@ -118,9 +123,9 @@ { "kind": "local", "title": "当前本地版本", - "value": "main · 0.4.0 closure", - "state": "ready", - "detail": "双 Adapter、Evidence 绑定、原生 Validator 收据、双语 README、版本事实与远端裁决已进入 main；本地合并后 190 tests 通过。" + "value": "codex/oss-release-readiness · local candidate", + "state": "progress", + "detail": "产品 0.4.0 基线之上已补齐不可变 CI、稳定安装和公开协作合同；尚未推送或改变远端 Release 状态。" }, { "kind": "remote", @@ -323,6 +328,12 @@ "title": "0.4.0 远端封板", "detail": "main 与 GitHub description/topics 已同步；run 30734873022 的 Ubuntu / Windows × Python 3.12 / 3.13 四项全部成功。未创建 Release 或 Git Tag。", "state": "done" + }, + { + "id": "N9", + "title": "v0.4.0 正式开源发布", + "detail": "本地仓库合同、191 tests、Validator、链接与真实双产物均通过；下一步是 ready PR、PR/main 双阶段 CI、可校验 Release 资产、Private Vulnerability Reporting 与 main 保护。", + "state": "active" } ], "work_lanes": { @@ -332,12 +343,20 @@ { "title": "0.4.0 双 Adapter 用户路径", "detail": "本地主线已交付：Adapter Router 支持 codex-skill / compact-prompt 二选一；Adapter 中立 Evidence、Codex 原生兼容门与两条真实 verify 路径均已接通。" + }, + { + "title": "v0.4.0 稳定开源分发", + "detail": "当前 active mainline：让用户从不可变 Tag 安装，并让 Artifact、SHA-256、CI 与仓库权限形成可复核发布链。" } ] }, "validation": { "label": "验证 · 绑定具体风险", "items": [ + { + "title": "正式发布双阶段 CI", + "detail": "等待本地出口后执行 PR 矩阵与合并 commit 的 main 矩阵；任一失败都停止 Tag 与 Release。" + }, { "title": "0.4.0 最终远端 CI", "detail": "run 30734873022 已 4 / 4 通过；0.4.0 的本地与远端出口均闭合。" @@ -374,6 +393,10 @@ { "title": "治理记录一致性", "detail": "R-020/R-021/R-024/R-025、版本、许可证、安装、产品审计与最终 CI 均已同步。" + }, + { + "title": "开源协作与安全入口", + "detail": "Security、Code of Conduct、Bug/Feature Issue Forms、PR 模板、稳定安装路径与不可变 CI revision 已在本地候选形成。" } ] }, @@ -382,7 +405,7 @@ "items": [ { "title": "0.4.0 边界外能力", - "detail": "Runtime、Override、Subloop、Library Edition、多 Loop、发布、调度、GitHub Release 与 Git Tag 不进入当前执行队列；它们不是当前双 Adapter 用户路径的未接接口。" + "detail": "Runtime、Override、Subloop、Library Edition、多 Loop、运行时发布与调度不进入当前执行队列；v0.4.0 GitHub Release 与 Git Tag 已转入正式开源发布主线。" } ] } @@ -393,13 +416,13 @@ "Subloop", "Library Edition", "多 Loop 构建", - "发布与调度" + "运行时发布与调度" ], "risks": [ { "level": "medium", - "title": "GitHub Actions action 版本存在弃用提示", - "detail": "checkout@v4 与 setup-python@v5 在当前托管运行器上被提示仍以 Node 20 为目标；GitHub 强制使用 Node 24 后本次 4 / 4 成功，因此登记为非阻塞维护项。" + "title": "正式发布仍依赖远端不可逆门槛", + "detail": "本地合同完成不等于 Release 已存在；PR/main CI、Tag、资产摘要、私密漏洞报告与 main 保护必须逐项回读成功，任一失败都保持 RELEASE CANDIDATE。" }, { "level": "medium", @@ -459,6 +482,10 @@ { "state": "ready", "title": "0.4.0 main 集成、GitHub 元数据与远端 CI" + }, + { + "state": "progress", + "title": "v0.4.0 正式开源 Release、资产摘要与 main 保护" } ], "known_limits": [ @@ -480,6 +507,16 @@ } ], "activity": [ + { + "date": "2026-08-01", + "title": "v0.4.0 正式发布本地出口通过", + "detail": "191 tests、compileall、Schema、54 份 Markdown、当前 Codex Validator 与真实 Skill/Prompt 双构建通过；Skill Creator PRO quality lint 的单条启发式提醒经复核为必要护栏。" + }, + { + "date": "2026-08-01", + "title": "v0.4.0 正式开源发布合同本地就绪", + "detail": "已固定 checkout@v7.0.1、setup-python@v7.0.0 与 Skill Creator PRO revision；稳定 Tag 安装路径、Security、Code of Conduct、Issue Forms 和 PR 模板已通过本地合同检查。外部发布事实继续 pending。" + }, { "date": "2026-08-01", "title": "PASS · 0.4.0 双输出封板", diff --git a/docs/plans/2026-08-01-open-source-release-readiness.md b/docs/plans/2026-08-01-open-source-release-readiness.md new file mode 100644 index 0000000..35b568e --- /dev/null +++ b/docs/plans/2026-08-01-open-source-release-readiness.md @@ -0,0 +1,292 @@ +# Loop Craft 0.4.0 Open-Source Release Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Publish the already validated Loop Craft 0.4.0 product slice as a reproducible, governable GitHub Release with a stable Skill archive and protected main branch. + +**Architecture:** Repository contracts are enforced by one deterministic integration test, then consumed by the existing GitHub Actions matrix. A feature PR proves the repository changes before merge; the merged commit is the only source for the release archive, tag and checksums. GitHub settings are applied after the release so protection cannot block the release integration itself. + +**Tech Stack:** Markdown, GitHub Issue Forms YAML, GitHub Actions YAML, Python 3.12+, pytest, git, GitHub CLI and REST API. + +--- + +### Task 1: Pin the release CI supply chain + +**Files:** +- Create: `tests/integration/test_repository_release_contract.py` +- Modify: `.github/workflows/validate.yml` + +- [ ] **Step 1: Write the failing CI contract test** + +Add assertions that the workflow contains read-only contents permission, `workflow_dispatch`, immutable Action SHAs with readable version comments, and the pinned Skill Creator PRO revision: + +```python +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +WORKFLOW = ROOT / ".github" / "workflows" / "validate.yml" + + +def test_release_workflow_pins_every_external_checkout() -> None: + text = WORKFLOW.read_text(encoding="utf-8") + assert "permissions:\n contents: read" in text + assert "workflow_dispatch:" in text + assert "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1" in text + assert "actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0" in text + assert "ref: eb23656e56ea3555599a6c5278a8b5834dc56b6d" in text +``` + +- [ ] **Step 2: Run the test and verify RED** + +Run: `python -m pytest tests/integration/test_repository_release_contract.py -q` + +Expected: failure because the workflow still uses floating Action majors and no Skill Creator PRO `ref`. + +- [ ] **Step 3: Make the workflow deterministic** + +Add: + +```yaml +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read +``` + +Replace both checkout calls and setup-python with the immutable SHAs in Step 1. Add +`ref: eb23656e56ea3555599a6c5278a8b5834dc56b6d` to the external repository checkout. + +- [ ] **Step 4: Run the targeted test and verify GREEN** + +Run: `python -m pytest tests/integration/test_repository_release_contract.py -q` + +Expected: `1 passed`. + +- [ ] **Step 5: Commit** + +```text +git add .github/workflows/validate.yml tests/integration/test_repository_release_contract.py +git commit -m "ci: pin release validation dependencies" +``` + +### Task 2: Add the minimum open-source governance surface + +**Files:** +- Create: `SECURITY.md` +- Create: `CODE_OF_CONDUCT.md` +- Create: `.github/ISSUE_TEMPLATE/bug_report.yml` +- Create: `.github/ISSUE_TEMPLATE/feature_request.yml` +- Create: `.github/ISSUE_TEMPLATE/config.yml` +- Create: `.github/pull_request_template.md` +- Modify: `tests/integration/test_repository_release_contract.py` + +- [ ] **Step 1: Extend the contract test and verify RED** + +Assert every file exists and assert the security policy points to +`https://github.com/Conradgui/loop-craft/security/advisories/new`. Assert the Bug form requests +Loop Craft version, entry route, selected Adapter, reproduction, expected/actual behavior and +Evidence redaction. Assert the PR template requests user impact, validation and boundaries. + +Run: `python -m pytest tests/integration/test_repository_release_contract.py -q` + +Expected: failure listing the missing community files. + +- [ ] **Step 2: Add `SECURITY.md` and `CODE_OF_CONDUCT.md`** + +Security must support 0.4.x, direct vulnerabilities to private reporting, forbid posting raw +conversations/Evidence/secrets in public Issues, state that Loop Craft can read/write local +files only under approved scope, and give a best-effort acknowledgement target without a +guaranteed remediation SLA. Conduct reports use the same private channel when confidentiality +is needed because no public maintainer email exists. + +- [ ] **Step 3: Add structured Issue and PR templates** + +Use GitHub Issue Forms with required acknowledgements for redaction and scope. Disable blank +Issues and add Security plus Discussions-independent documentation contact links. The PR +template must distinguish checks run from checks deliberately not run. + +- [ ] **Step 4: Run the targeted test and static YAML load** + +Run: + +```text +python -m pytest tests/integration/test_repository_release_contract.py -q +python -c "import pathlib,yaml; [yaml.safe_load(p.read_text(encoding='utf-8')) for p in pathlib.Path('.github/ISSUE_TEMPLATE').glob('*.yml')]; print('issue forms yaml ok')" +``` + +Expected: contract passes and all three Issue Form YAML files parse. + +- [ ] **Step 5: Commit** + +```text +git add SECURITY.md CODE_OF_CONDUCT.md .github tests/integration/test_repository_release_contract.py +git commit -m "docs: add open-source governance contracts" +``` + +### Task 3: Make the stable release path discoverable + +**Files:** +- Modify: `README.md` +- Modify: `README.zh.md` +- Modify: `CONTRIBUTING.md` +- Modify: `CHANGELOG.md` +- Modify: `tests/integration/test_repository_release_contract.py` + +- [ ] **Step 1: Extend the contract test and verify RED** + +Require both READMEs to link to `tree/v0.4.0/loop-craft`, Security, Issues, Pull Requests, +Contributing and Code of Conduct. Require CONTRIBUTING to direct suspected vulnerabilities to +SECURITY instead of public Issues. + +- [ ] **Step 2: Update user and contributor navigation** + +Keep `main` documentation links for living docs, but change the default installer prompt to +the immutable `v0.4.0/loop-craft` path. Add a compact Community section to both READMEs and a +Security section to CONTRIBUTING. Record governance and stable-install changes under 0.4.0 in +CHANGELOG without claiming the GitHub Release exists yet. + +- [ ] **Step 3: Run the targeted contract and local-link checks** + +Run the contract test plus the existing Markdown link checker logic over root, docs and +`loop-craft/`. Expected: 0 broken local links. + +- [ ] **Step 4: Commit** + +```text +git add README.md README.zh.md CONTRIBUTING.md CHANGELOG.md tests/integration/test_repository_release_contract.py +git commit -m "docs: expose stable release and community paths" +``` + +### Task 4: Project the release candidate truthfully + +**Files:** +- Modify: `dashboard/status.json` +- Create: `docs/records/2026-08-01-v0.4.0-open-source-release.md` + +- [ ] **Step 1: Update the dashboard to RELEASE CANDIDATE** + +Keep product completion at 100%, add a separate release-readiness milestone/lane stating that +repository contracts are local-complete while PR CI, main CI, Release and branch protection are +pending. Do not reduce the delivered product capability or claim the external actions occurred. + +- [ ] **Step 2: Create the execution record** + +Record the immutable revisions, intended GitHub settings, local validation commands and blank +fields for observed PR/main run IDs and Release URL. Blank fields must be labeled pending, not +fabricated. + +- [ ] **Step 3: Validate and commit** + +Parse `dashboard/status.json`, run `git diff --check`, then commit: + +```text +git add dashboard/status.json docs/records/2026-08-01-v0.4.0-open-source-release.md +git commit -m "docs: stage 0.4.0 open-source release" +``` + +### Task 5: Run the complete local release gate + +**Files:** none unless a verification failure reveals an in-scope defect. + +- [ ] **Step 1: Run deterministic checks** + +Run `python -m compileall -q loop-craft/scripts tests`, schema meta-validation, dashboard JSON, +root/docs/Skill local links, current Codex `quick_validate.py`, and Skill Creator PRO quality +lint at the pinned revision. + +- [ ] **Step 2: Run the complete test suite** + +Run: `python -m pytest -q` + +Expected: 191 tests pass after adding the repository contract test. + +- [ ] **Step 3: Run same-definition dual builds** + +Build the valid fixture with `codex-skill` plus the current native validator and with +`compact-prompt`; run `verify` on both. Expected: both `clean`, Skill has the native receipt, +Prompt does not. + +- [ ] **Step 4: Review scope** + +Confirm `git status --short` is clean, inspect `main..HEAD`, and confirm no Core/Adapter/Schema +behavior file changed. + +### Task 6: Publish through a ready PR and merge + +**Files:** no new repository files. + +- [ ] **Step 1: Push the release branch** + +Push `codex/oss-release-readiness` with upstream tracking. + +- [ ] **Step 2: Open a ready-for-review PR** + +Title: `Prepare Loop Craft 0.4.0 for formal open-source release`. + +Body must cover supply-chain pinning, stable install path, governance contracts, local evidence, +no Core behavior changes and deferred non-goals. This PR is ready, not draft, because the user +explicitly requested completion through GitHub. + +- [ ] **Step 3: Wait for PR CI and merge** + +Require all four matrix jobs to succeed. Merge without force-push, then wait for the merge +commit's `main` push workflow to succeed 4/4. Stop if either run fails. + +### Task 7: Create the immutable release and GitHub protections + +**Files:** temporary release assets only; no generated archive enters Git. + +- [ ] **Step 1: Build release assets from the verified merge commit** + +Use `git archive` to create `loop-craft-v0.4.0.zip` containing only `loop-craft/` under a +versioned prefix. Write its lowercase SHA-256 line to `SHA256SUMS.txt`, then independently +recompute and compare the digest. + +- [ ] **Step 2: Create Tag and Release** + +Create annotated `v0.4.0` at the verified merge commit. Create a non-draft, non-prerelease +GitHub Release with bounded claims, install instructions, CI run link, explicit limitations and +both assets. Stop instead of overwriting if Tag or Release already exists. + +- [ ] **Step 3: Apply repository settings** + +Enable private vulnerability reporting, disable the unused Wiki, and protect `main` with strict +required checks for the four matrix job names. Enforce protection for administrators, disallow +force pushes and deletion, require conversation resolution, and do not require an impossible +self-approval. + +- [ ] **Step 4: Read back every external fact** + +Verify Tag target, Release assets/digests, Private Vulnerability Reporting status, Wiki disabled, +Community Profile, branch protection and `origin/main`. + +### Task 8: Close through the protected branch and hand off + +**Files:** +- Modify: `dashboard/status.json` +- Modify: `docs/records/2026-08-01-v0.4.0-open-source-release.md` + +- [ ] **Step 1: Create a closure branch and record only observed remote results** + +Create `codex/oss-release-closure` from the protected `main`. Write actual PR URL, PR and main CI +run IDs, verified release commit, Release URL, archive digest, GitHub settings results and any +non-blocking residual into the record and dashboard. + +- [ ] **Step 2: Run support-only checks and commit** + +Parse dashboard JSON, verify Markdown links and run `git diff --check`. Commit on the closure +branch with: + +```text +git commit -m "docs: record 0.4.0 open-source release [skip ci]" +``` + +- [ ] **Step 3: Push closure facts through a second PR** + +Push the closure branch, open a ready PR, wait for its four required checks and merge through the +new protection rule. Wait for the resulting `main` run, confirm local HEAD equals `origin/main`, +and keep `v0.4.0` on the earlier verified product commit. diff --git a/docs/records/2026-08-01-v0.4.0-open-source-release.md b/docs/records/2026-08-01-v0.4.0-open-source-release.md new file mode 100644 index 0000000..ba03b87 --- /dev/null +++ b/docs/records/2026-08-01-v0.4.0-open-source-release.md @@ -0,0 +1,72 @@ +# Loop Craft v0.4.0 正式开源发布记录 + +> 日期：2026-08-01；分支：`codex/oss-release-readiness`； +> 当前判断：`RELEASE CANDIDATE`——产品已通过，正式发布外部门槛尚未执行 + +## 发布目标 + +本轮不修改 Loop Craft 的 Core、Adapter、Schema 或 Agent 行为。目标是让已经通过产品验收的 +0.4.0 具备稳定安装、可复现 CI、公开协作、安全报告、版本资产和受保护主分支。 + +设计与计划： + +- `docs/specs/2026-08-01-open-source-release-readiness-design.md` +- `docs/plans/2026-08-01-open-source-release-readiness.md` + +## 不可变外部 revision + +| 依赖 | 可读版本 | 固定 revision | 来源 | +|---|---|---|---| +| actions/checkout | v7.0.1 | `3d3c42e5aac5ba805825da76410c181273ba90b1` | GitHub 官方 release tag | +| actions/setup-python | v7.0.0 | `5fda3b95a4ea91299a34e894583c3862153e4b97` | GitHub 官方 release tag | +| Skill Creator PRO | pinned source | `eb23656e56ea3555599a6c5278a8b5834dc56b6d` | Conradgui/skill-creator-pro | + +## 已观察的本地事实 + +| 检查 | 结果 | +|---|---| +| 开始前基线 | `190 passed in 11.40s` | +| 完整候选测试 | `191 passed in 9.85s` | +| Python 编译 | passed | +| Schema meta-validation | accepted-definition / entry-evidence passed | +| 当前 Codex validator | `Skill is valid!` | +| Skill Creator PRO quality lint | 1 个启发式提醒；复核为审批、权限与 provenance 的必要护栏 | +| 发布仓库合同测试 | `1 passed` | +| Issue Form YAML | 3 files parsed | +| Root / docs / Skill Markdown links | 54 files, 0 broken | +| 稳定安装入口 | `tree/v0.4.0/loop-craft` 已进入双语 README | +| 社区合同 | Security、Code of Conduct、Bug/Feature Forms、PR template 本地存在 | +| Codex Skill 真实构建 | clean；`sha256:23ac2315e146fcb6b278b004fed44e9a4473425147449b348ffefee21939f357` | +| Compact Prompt 真实构建 | clean；`sha256:fcc5b9888a3dd7634521146ced53c597452dbe1273d424ea3b5143f67b90f4bd` | +| 双产物 Execution IR | digest 相同 | + +本次双构建位于 +`C:/Users/Administrator/AppData/Local/Temp/loopcraft-release-392ca816358f48d689eacebe899d638b`。 +它不属于仓库，本轮没有删除该临时验证目录。 + +## 远端发布门 + +以下项目只有在真实执行并回读后才会由 `PENDING` 改为观测结果： + +| 发布事实 | 当前状态 | +|---|---| +| 实施 PR URL / commit | PENDING | +| PR CI run · Ubuntu / Windows × Python 3.12 / 3.13 | PENDING | +| main merge commit / main CI run | PENDING | +| `v0.4.0` Tag target | PENDING | +| GitHub Release URL | PENDING | +| `loop-craft-v0.4.0.zip` SHA-256 | PENDING | +| Private Vulnerability Reporting | PENDING | +| Wiki disabled | PENDING | +| main branch protection | PENDING | +| closure PR / final main CI | PENDING | + +## 停止条件 + +- 任一四项矩阵失败； +- Tag 或 Release 已存在且目标不一致； +- Release 资产的重新计算摘要不等于记录摘要； +- GitHub 设置 API 权限不足； +- diff 出现未经设计批准的 Core、Adapter、Schema 或 Skill 行为修改。 + +停止时保留已经通过的本地提交和远端 PR，不伪造 PASS、不覆盖 Tag，也不通过强推绕过保护。 diff --git a/docs/specs/2026-08-01-open-source-release-readiness-design.md b/docs/specs/2026-08-01-open-source-release-readiness-design.md new file mode 100644 index 0000000..3f6ac42 --- /dev/null +++ b/docs/specs/2026-08-01-open-source-release-readiness-design.md @@ -0,0 +1,117 @@ +# Loop Craft 0.4.0 正式开源发布设计 + +> 日期：2026-08-01 +> 状态：已批准——用户在收到发布就绪度审计与四项建议后，明确要求完成迭代并提交 GitHub + +## 1. 目标 + +把当前已经公开、产品链路通过的 Loop Craft 0.4.0 候选，收口为一个可被陌生用户安装、可被 +外部贡献者参与、可被维护者稳定复现，并拥有正式版本入口的 GitHub 开源发布。 + +本轮成功不是“多几个社区文件”，而是同时满足： + +1. `v0.4.0` 指向的源码 commit 本身通过 Ubuntu / Windows × Python 3.12 / 3.13 CI； +2. CI 使用的第三方 Action 与 Skill Creator PRO revision 都不可漂移； +3. 用户能从稳定版本链接安装 Skill，而不是被迫追踪可变的 `main`； +4. 漏洞、Bug、功能建议与 Pull Request 都有明确入口； +5. GitHub Release 提供发布说明、可安装压缩包和 SHA-256； +6. `main` 在发布后受保护，不能绕过 CI、强推或删除。 + +## 2. 方案选择 + +### A. 最小但完整的正式发布（采用） + +补齐供应链固定、安全与协作文件、稳定安装链接、PR/CI 发布路径、Release 资产和分支保护。 +它直接关闭本次审计发现的发布缺口，不引入文档站、遥测、包管理器或新的 Core 能力。 + +### B. 只补 GitHub 模板后立即打 Tag（拒绝） + +成本最低，但外部 Validator 仍从可变默认分支拉取，Tag 也可能没有精确 CI 证据。它提高了 +仓库外观，却没有解决可复现性这一更重要的工程风险。 + +### C. 一次建设完整社区平台（暂不采用） + +同时增加 Docs Site、示例库、Discussions、覆盖率服务、Dependabot、路线图自动化和多渠道 +支持。这会显著增加维护面，并且没有证据表明 0.4.0 首发需要这些能力。 + +## 3. 仓库内变更 + +### 3.1 可复现 CI + +修改 `.github/workflows/validate.yml`： + +- 声明最小 `contents: read` 权限； +- 增加 `workflow_dispatch`，允许对指定最终 commit 运行发布门； +- 将 `actions/checkout` 固定为 `v7.0.1` 对应 commit + `3d3c42e5aac5ba805825da76410c181273ba90b1`； +- 将 `actions/setup-python` 固定为 `v7.0.0` 对应 commit + `5fda3b95a4ea91299a34e894583c3862153e4b97`； +- 将 Skill Creator PRO checkout 固定到 + `eb23656e56ea3555599a6c5278a8b5834dc56b6d`； +- 保留现有四平台矩阵、Skill validator、真实 build/verify 与 drift negative case。 + +Action revision 来自各自 GitHub 官方仓库的 release tag；注释同时保留可读版本号和不可变 SHA。 + +### 3.2 安全与社区合同 + +新增： + +- `SECURITY.md`：支持版本、私密漏洞报告入口、本地文件与权限边界、响应预期； +- `CODE_OF_CONDUCT.md`：简洁的社区行为与执行合同；敏感报告使用 GitHub 私密报告入口， + 不编造维护者邮箱； +- `.github/ISSUE_TEMPLATE/bug_report.yml`：要求版本、入口、Adapter、最小复现、预期/实际结果、 + Evidence 脱敏确认； +- `.github/ISSUE_TEMPLATE/feature_request.yml`：要求用户价值、当前替代方案、产品边界与证据； +- `.github/ISSUE_TEMPLATE/config.yml`：关闭空白 Issue，并将安全问题导向私密报告； +- `.github/pull_request_template.md`：用户能力、范围、验证、未运行项目和边界清单。 + +修改 `README.md`、`README.zh.md` 与 `CONTRIBUTING.md`，增加稳定版本安装、Security、Issues、 +Pull Requests 和 Code of Conduct 入口。开发文档继续保留 `main` 路径；用户安装默认指向 +`v0.4.0/loop-craft`。 + +### 3.3 项目事实 + +更新 `CHANGELOG.md`、`dashboard/status.json` 与发布执行记录，区分： + +- 产品 0.4.0 已通过； +- 正式开源发布门正在执行； +- Release 与分支保护只有在远端动作实际成功后才写成完成。 + +## 4. GitHub 交付流程 + +1. 在 `codex/oss-release-readiness` 隔离分支实现并做静态检查； +2. 运行完整本地出口，推送分支并创建 ready-for-review PR； +3. 等待 PR 的四项矩阵通过后合并到 `main`； +4. 等待合并 commit 的 `main` CI 四项通过； +5. 从该已验证 commit 生成 `loop-craft-v0.4.0.zip` 与 `SHA256SUMS.txt`； +6. 创建 `v0.4.0` annotated Tag 和 GitHub Release，附两份资产； +7. 启用 GitHub Private Vulnerability Reporting，关闭空 Wiki； +8. 启用 `main` 保护：严格要求四个矩阵状态、禁止强推和删除，不要求维护者自己批准自己的 PR； +9. 分支保护启用后，从 `main` 创建只含看板与执行记录的 closure 分支，通过第二个 PR 写入 + Release URL、CI run 与保护结果；等待 closure PR 与合并后的 `main` CI 成功。 + +Tag 始终指向已通过 CI 的产品/发布 commit。最后的事实投影通过受保护分支正常合并，不移动 +Tag，也不被描述为新的产品版本。 + +## 5. 错误与停止边界 + +- 任一 PR 或 `main` CI 失败：停止 Tag 与 Release，先修复并重新获得完整矩阵结果； +- Release 资产摘要与上传文件不一致：停止发布，重新从已验证 commit 构建； +- Tag 或 Release 已存在但目标不一致：不覆盖、不强推，停止并报告； +- GitHub 设置 API 权限不足：代码和 Release 可以保留，但不得声称分支保护或私密报告已启用； +- 不创建 PyPI 包，不把 `loopcraft-development` 宣称为用户安装包； +- 不修改 Core、Adapter、Schema 或 Skill 行为；Runtime、多 Loop、Override、Subloop 继续在范围外。 + +## 6. 验证 + +本地：YAML/JSON 解析、本地 Markdown 链接、官方 Skill validator、`compileall`、190 项测试和 +同一 Definition 的真实 Skill/Prompt build + verify。 + +远端：PR 与合并 commit 的 GitHub Actions 四项矩阵。发布后回读 Tag target、Release assets、 +SHA-256、Private Vulnerability Reporting、Wiki 状态、Community Profile 与 branch protection。 + +## 7. 不进入本轮 + +文档站、GitHub Pages、Discussions、Sponsor、PyPI、自动发布流水线、覆盖率 SaaS、Dependabot、 +CODEOWNERS 强制审批、示例库扩张和新的产品能力均不进入本轮。它们可在真实社区使用信号出现后 +单独决策。 diff --git a/tests/integration/test_repository_release_contract.py b/tests/integration/test_repository_release_contract.py new file mode 100644 index 0000000..3349529 --- /dev/null +++ b/tests/integration/test_repository_release_contract.py @@ -0,0 +1,75 @@ +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +WORKFLOW = ROOT / ".github" / "workflows" / "validate.yml" + + +def test_repository_is_ready_for_a_reproducible_public_release() -> None: + workflow = WORKFLOW.read_text(encoding="utf-8") + + assert "permissions:\n contents: read" in workflow + assert "workflow_dispatch:" in workflow + assert "push:\n branches: [main]" in workflow + assert ( + "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1" + in workflow + ) + assert ( + "actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0" + in workflow + ) + assert "ref: eb23656e56ea3555599a6c5278a8b5834dc56b6d" in workflow + + required_files = [ + "SECURITY.md", + "CODE_OF_CONDUCT.md", + ".github/ISSUE_TEMPLATE/bug_report.yml", + ".github/ISSUE_TEMPLATE/feature_request.yml", + ".github/ISSUE_TEMPLATE/config.yml", + ".github/pull_request_template.md", + ] + missing = [path for path in required_files if not (ROOT / path).is_file()] + assert missing == [], f"missing public repository contracts: {missing}" + + security = (ROOT / "SECURITY.md").read_text(encoding="utf-8") + assert "https://github.com/Conradgui/loop-craft/security/advisories/new" in security + assert "0.4.x" in security + assert "Evidence" in security + + bug_form = (ROOT / ".github/ISSUE_TEMPLATE/bug_report.yml").read_text( + encoding="utf-8" + ) + for field in ( + "Loop Craft version", + "Entry route", + "Selected Adapter", + "Minimal reproduction", + "Expected behavior", + "Actual behavior", + "Evidence redaction", + ): + assert field in bug_form + + pull_request = (ROOT / ".github/pull_request_template.md").read_text( + encoding="utf-8" + ) + for section in ("User impact", "Scope", "Validation", "Not run", "Boundaries"): + assert section in pull_request + + stable_skill = "https://github.com/Conradgui/loop-craft/tree/v0.4.0/loop-craft" + for readme_name in ("README.md", "README.zh.md"): + readme = (ROOT / readme_name).read_text(encoding="utf-8") + assert stable_skill in readme + for community_path in ( + "SECURITY.md", + "CONTRIBUTING.md", + "CODE_OF_CONDUCT.md", + "https://github.com/Conradgui/loop-craft/issues", + "https://github.com/Conradgui/loop-craft/pulls", + ): + assert community_path in readme + + contributing = (ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8") + assert "SECURITY.md" in contributing + assert "Do not open a public Issue" in contributing