@t275005746/gse 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to GSE
+
+Thanks for helping improve GSE.
+
+GSE is a workflow skill and project scaffold for agent-assisted software engineering. Contributions should make long-running project work more explicit, verifiable, portable, or easier to recover.
+
+## What To Contribute
+
+Good contributions usually fit one of these paths:
+
+- Improve the Goal -> Spec -> Execute -> Evidence -> Learn workflow.
+- Add or tighten an audit script.
+- Improve project scaffold templates.
+- Clarify host adapter boundaries.
+- Add examples that prove a workflow in a small, reproducible project.
+- Fix documentation that overstates support or leaves future agents guessing.
+
+Avoid changes that make optional tools mandatory unless there is a clear fallback path.
+
+## Development Rules
+
+- Keep `SKILL.md` short and route details into `references/`.
+- Prefer scripts and templates over repeated prose when behavior must be repeatable.
+- Do not claim support for a host, marketplace, model, MCP server, subagent, or slash command unless there is evidence.
+- Keep evidence statuses honest: `result`, `verified`, or `accepted`.
+- Do not choose a public license on behalf of the owner. Use `references/public-release.md` and `scripts/record-public-release.mjs`.
+
+## Validation
+
+Before proposing a change, run:
+
+```text
+node scripts/validate-gse.mjs --root <gse-root> --json
+```
+
+For packaging or install behavior, also run:
+
+```text
+node scripts/audit-distribution.mjs --root <gse-root> --json
+node scripts/audit-remote-distribution.mjs --root <gse-root> --json
+```
+
+For public release handoff, also run:
+
+```text
+node scripts/audit-release-bundle.mjs --root <gse-root> --json
+node scripts/audit-public-release-metadata.mjs --root <gse-root> --json
+```
+
+## Evidence
+
+Record meaningful changes in `.gse/evidence/YYYY-MM-DD.md` and append a compact record to `.gse/evidence/index.jsonl`.
+
+Do not paste secrets, raw provider payloads, private reasoning, long command logs, screenshots, or noisy transient output into evidence files.
+
+## Review
+
+Review should check:
+
+- The change maps to `.gse/goal-map.md` or the design master plan.
+- Scope did not expand silently.
+- Validation covers the changed behavior.
+- Unsupported claims remain explicit.
+- Installed-copy validation still passes when package behavior changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GSE contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# GSE
+
+English | [简体中文](README.zh-CN.md)
+
+Goal-Spec-Evidence Engineering for long-running agent-assisted software projects.
+
+GSE gives coding agents and human teams a small project workspace for goals, specs, execution notes, evidence, and handoff. It keeps the next change clear, the proof close to the work, and future sessions easy to resume.
+
+It is designed for agentic engineering, spec-driven development, SDD-style project work, and evidence-based delivery across different AI coding hosts.
+
+```text
+Goal -> Spec -> Execute -> Evidence -> Learn
+```
+
+## Highlights
+
+- Project-local `.gse/` workspace for durable engineering context
+- Goal maps, change specs, quality gates, evidence logs, and handoff notes
+- Lite, standard, and enterprise scaffolds for different project sizes
+- Portable `/gse ...` command semantics for Codex, Claude Code, Hermes-style runtimes, WorkBuddy, and similar agent hosts
+- Focused validation profiles for day-to-day work and release checks
+- Optional adapters for host folders, LSP notes, MCP notes, hooks, plugins, and project skills
+- Release, packaging, public-collaboration, and evidence-gate workflows for mature projects
+
+## Installation
+
+Use GSE from a checked-out copy:
+
+```bash
+node scripts/validate-gse.mjs --root . --json
+```
+
+Package a checked-out copy for handoff:
+
+```bash
+node scripts/package-gse.mjs --root . --out <package-dir> --label <release-label>
+```
+
+Install from a local package:
+
+```bash
+node scripts/install-gse.mjs --source <package-dir> --target <install-skill-dir>
+```
+
+Install from a URL-shaped package source:
+
+```bash
+node scripts/install-gse.mjs --source-url <file-or-http-package-url> --target <install-skill-dir>
+```
+
+For release bundles, signing, and trust records, see `references/packaging.md`.
+
+## Quick Start
+
+Initialize GSE in a project:
+
+```bash
+node scripts/init-project.mjs --target <project-root>
+```
+
+Choose a scaffold explicitly when you already know the project shape:
+
+```bash
+node scripts/init-project.mjs --target <project-root> --mode lite
+node scripts/init-project.mjs --target <project-root> --mode standard
+node scripts/init-project.mjs --target <project-root> --mode enterprise
+```
+
+Inspect a project without writing files:
+
+```bash
+node scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+Validate this GSE package:
+
+```bash
+node scripts/validate-gse.mjs --root . --json
+```
+
+Check Node package metadata before publishing or handoff:
+
+```bash
+node scripts/audit-npm-package-metadata.mjs --root . --json
+node scripts/audit-npm-tarball-install.mjs --root . --json
+node scripts/audit-npm-publish-dry-run.mjs --root . --json
+npm pack --dry-run --json
+```
+
+## When To Use GSE
+
+Use GSE when:
+
+- the project will continue across many agent sessions,
+- requirements and decisions are getting buried in chat history,
+- each change needs a clear scope and acceptance check,
+- multiple agents, workers, tools, or model routes touch the same project,
+- you want evidence before calling work done.
+
+For a small one-off task, use the lightest path. For a product, runtime, platform, or open-source release, use the stricter gates.
+
+## How It Works
+
+GSE keeps five things visible:
+
+| Step | Purpose |
+|---|---|
+| Goal | Keep the north star, current focus, risks, and next slices visible. |
+| Spec | Define the current change before implementation drifts. |
+| Execute | Follow the project rules and existing code patterns. |
+| Evidence | Prove the change with focused tests, API smokes, browser smokes, review, or structural checks. |
+| Learn | Record reusable lessons and promote repeated failures into gates or templates. |
+
+The workflow scales by risk: light for small changes, stricter for shared behavior, release work, security-sensitive work, and cross-host claims.
+
+## What It Creates
+
+GSE creates a portable `.gse/` workspace inside the target project.
+
+| Mode | Adds | Good for |
+|---|---|---|
+| `lite` | Goal map, project profile, quality gates, tooling notes, evidence logs, change templates | Small projects, low-risk tasks, first adoption |
+| `standard` | Everything in `lite`, plus agent roles, dispatch notes, project skills, LSP/index notes | Projects that agents will continue over time |
+| `enterprise` | Everything in `standard`, plus hooks, MCP notes, plugins, release notes, incident review, audit notes, host adapters | Larger projects, multiple hosts, runtime integrations, governance |
+| `auto` | Selects a conservative scaffold from project signals | When you want GSE to choose |
+
+Large projects can start directly with `standard` or `enterprise`.
+
+## Project Layout
+
+Typical workspace:
+
+```text
+.gse/
+  README.md
+  project-profile.md
+  goal-map.md
+  goals/
+  quality-gates.md
+  tooling.md
+  changes/
+  evidence/
+  templates/
+```
+
+Standard and enterprise projects may also include:
+
+```text
+.gse/
+  agents/
+  skills/
+  lsp/
+  hooks/
+  mcp/
+  plugins/
+  release.md
+  incident-review.md
+  audit.md
+```
+
+Use `.gse/goal-map.md` as the short index. Put module-level detail under `.gse/goals/`. Keep existing product roadmaps, architecture docs, and project rules where they already live; point to them from GSE instead of copying them.
+
+## Commands
+
+GSE defines portable command meanings that agents can follow when they can read this skill:
+
+```text
+/gse help
+/gse init
+/gse adopt
+/gse continue
+/gse status
+/gse doctor
+/gse acceptance
+/gse owner-actions
+/gse probe
+/gse release
+/gse package
+/gse install
+/gse public-release
+/gse change
+/gse slice
+/gse verify
+/gse learn
+/gse audit
+/gse close
+```
+
+`/gse close` is a read-only readiness check. Use `scripts/close-change.mjs` when you need to archive a named change pack after evidence exists.
+
+Portable runner:
+
+```bash
+node scripts/gse.mjs continue --target <project-root>
+node scripts/run-gse-command.mjs --target <project-root> --command "/gse continue"
+node scripts/run-gse-command.mjs --target <project-root> --command "/gse learn --summary <lesson>" --execute --json
+```
+
+Validation profiles:
+
+```bash
+node scripts/run-validation-profile.mjs --target <project-root> --profile lite
+node scripts/run-validation-profile.mjs --target <project-root> --profile standard
+node scripts/run-validation-profile.mjs --target <project-root> --profile enterprise
+node scripts/run-validation-profile.mjs --target <project-root> --profile release
+```
+
+## Evidence Model
+
+GSE uses three evidence levels:
+
+```text
+result -> verified -> accepted
+```
+
+- `result`: an artifact exists or a command ran.
+- `verified`: focused checks prove the behavior in the current environment.
+- `accepted`: the project owner, policy, CI gate, release gate, review gate, or product acceptance gate accepts the verified result.
+
+This keeps normal product work fast while still making release, security, and cross-host claims auditable.
+
+## Documentation
+
+- `SKILL.md`: agent entrypoint and routing rules
+- `references/`: workflow references and deeper operating notes
+- `scripts/`: project bootstrap, validation, release, and audit helpers
+- `assets/templates/`: reusable records and handoff templates
+- `README.zh-CN.md`: Chinese README
+
+## Community
+
+GateHub ([gatehub.top](https://gatehub.top/)) supports GSE development and contributor collaboration.
+
+## License
+
+MIT. See `LICENSE`.

package/README.zh-CN.md

@@ -0,0 +1,236 @@
+# GSE
+
+[English](README.md) | 简体中文
+
+面向长期 agent 辅助软件项目的 Goal-Spec-Evidence Engineering。
+
+GSE 给 coding agent 和团队一个很小的项目工作区，用来保存目标、规格、执行说明、证据和交接信息。它让下一步更清楚，让验证贴近代码，让后续会话更容易接上。
+
+它适合 agentic engineering、spec-driven development、SDD 风格的项目推进，也适合需要证据闭环的 AI coding agent 工作流。
+
+```text
+Goal -> Spec -> Execute -> Evidence -> Learn
+```
+
+## 亮点
+
+- 项目本地 `.gse/` 工作区，用来保存长期工程上下文
+- 目标地图、变更规格、质量门、证据日志和交接记录
+- `lite`、`standard`、`enterprise` 三种脚手架，适配不同规模项目
+- 面向 Codex、Claude Code、Hermes-style runtimes、WorkBuddy 等 host 的可迁移 `/gse ...` 命令语义
+- 面向日常开发和发布检查的 focused validation profiles
+- 可选 host folders、LSP、MCP、hooks、plugins、project skills 适配说明
+- 面向成熟项目的 release、packaging、public collaboration 和 evidence gate 工作流
+
+## 安装
+
+从已检出的 GSE 副本直接使用：
+
+```bash
+node scripts/validate-gse.mjs --root . --json
+```
+
+把已检出的副本打包给其他环境：
+
+```bash
+node scripts/package-gse.mjs --root . --out <package-dir> --label <release-label>
+```
+
+从本地包安装：
+
+```bash
+node scripts/install-gse.mjs --source <package-dir> --target <install-skill-dir>
+```
+
+从 URL 形式的包源安装：
+
+```bash
+node scripts/install-gse.mjs --source-url <file-or-http-package-url> --target <install-skill-dir>
+```
+
+发布包、签名和信任记录见 `references/packaging.md`。
+
+## 快速开始
+
+给项目初始化 GSE：
+
+```bash
+node scripts/init-project.mjs --target <project-root>
+```
+
+如果已经知道项目形态，可以直接指定模式：
+
+```bash
+node scripts/init-project.mjs --target <project-root> --mode lite
+node scripts/init-project.mjs --target <project-root> --mode standard
+node scripts/init-project.mjs --target <project-root> --mode enterprise
+```
+
+只读检查项目画像：
+
+```bash
+node scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+验证 GSE 包：
+
+```bash
+node scripts/validate-gse.mjs --root . --json
+```
+
+发布或交接前检查 Node package metadata：
+
+```bash
+node scripts/audit-npm-package-metadata.mjs --root . --json
+node scripts/audit-npm-tarball-install.mjs --root . --json
+node scripts/audit-npm-publish-dry-run.mjs --root . --json
+npm pack --dry-run --json
+```
+
+## 什么时候用 GSE
+
+适合这些情况：
+
+- 项目会跨很多 agent 会话持续推进，
+- 需求和决策开始埋在聊天历史里，
+- 每次变更都需要清楚的范围和验收方式，
+- 多个 agents、workers、tools 或 model routes 会碰同一个项目，
+- 希望先有证据，再说完成。
+
+小型一次性任务可以走最轻路径。产品、runtime、平台或开源发布可以启用更严格的质量门。
+
+## 工作方式
+
+GSE 始终让五件事可见：
+
+| 步骤 | 作用 |
+|---|---|
+| Goal | 记录北极星、当前焦点、风险和下一刀。 |
+| Spec | 在实现漂移前定义当前变更。 |
+| Execute | 按项目规则和现有代码模式执行。 |
+| Evidence | 用 focused tests、API smokes、browser smokes、review 或结构检查证明结果。 |
+| Learn | 记录可复用经验，把重复问题提升为质量门或模板。 |
+
+流程按风险伸缩：小变更保持轻量；共享行为、发布、安全敏感和跨 host 声明走更严格的验证。
+
+## 会创建什么
+
+GSE 会在目标项目里创建一个可迁移的 `.gse/` 工作区。
+
+| 模式 | 创建内容 | 适合场景 |
+|---|---|---|
+| `lite` | 目标地图、项目画像、质量门、工具说明、证据日志、变更模板 | 小项目、低风险任务、首次接入 |
+| `standard` | 包含 `lite`，并增加 agent 角色、派发说明、项目 skills、LSP/index 说明 | 会持续由 agent 接续开发的项目 |
+| `enterprise` | 包含 `standard`，并增加 hooks、MCP、plugins、release、incident review、audit、host adapters | 大型项目、多 host、runtime 集成、治理 |
+| `auto` | 根据项目线索选择保守脚手架 | 希望 GSE 自动选择时 |
+
+大项目第一次接入也可以直接使用 `standard` 或 `enterprise`。
+
+## 项目结构
+
+典型工作区：
+
+```text
+.gse/
+  README.md
+  project-profile.md
+  goal-map.md
+  goals/
+  quality-gates.md
+  tooling.md
+  changes/
+  evidence/
+  templates/
+```
+
+`standard` 和 `enterprise` 项目还可能包含：
+
+```text
+.gse/
+  agents/
+  skills/
+  lsp/
+  hooks/
+  mcp/
+  plugins/
+  release.md
+  incident-review.md
+  audit.md
+```
+
+`.gse/goal-map.md` 是短索引。模块级详情放在 `.gse/goals/`。已有产品路线图、架构文档和项目规则可以继续留在原位置，由 GSE 指向它们，不需要搬进 `.gse/`。
+
+## 命令
+
+GSE 定义了一组可迁移命令语义，能读取这个 skill 的 agent 可以按这些命令执行：
+
+```text
+/gse help
+/gse init
+/gse adopt
+/gse continue
+/gse status
+/gse doctor
+/gse acceptance
+/gse owner-actions
+/gse probe
+/gse release
+/gse package
+/gse install
+/gse public-release
+/gse change
+/gse slice
+/gse verify
+/gse learn
+/gse audit
+/gse close
+```
+
+`/gse close` 是只读的收口就绪检查。需要在证据存在后归档某个 change pack 时，使用 `scripts/close-change.mjs`。
+
+可迁移 runner：
+
+```bash
+node scripts/gse.mjs continue --target <project-root>
+node scripts/run-gse-command.mjs --target <project-root> --command "/gse continue"
+node scripts/run-gse-command.mjs --target <project-root> --command "/gse learn --summary <lesson>" --execute --json
+```
+
+验证 profile：
+
+```bash
+node scripts/run-validation-profile.mjs --target <project-root> --profile lite
+node scripts/run-validation-profile.mjs --target <project-root> --profile standard
+node scripts/run-validation-profile.mjs --target <project-root> --profile enterprise
+node scripts/run-validation-profile.mjs --target <project-root> --profile release
+```
+
+## 证据模型
+
+GSE 使用三层证据：
+
+```text
+result -> verified -> accepted
+```
+
+- `result`：产物存在，或者命令已经执行。
+- `verified`：focused checks 证明当前环境里的行为有效。
+- `accepted`：项目 owner、策略、CI gate、release gate、review gate 或产品验收门接受 verified 结果。
+
+这样日常产品切片可以保持快速，发布、安全和跨 host 声明也能被追踪和审计。
+
+## 文档
+
+- `SKILL.md`：agent 入口和路由规则
+- `references/`：工作流参考和更深的运行说明
+- `scripts/`：项目初始化、验证、发布和审计 helper
+- `assets/templates/`：可复用记录和交接模板
+- `README.md`：英文 README
+
+## 社区
+
+GateHub（[gatehub.top](https://gatehub.top/)）支持 GSE 的开发和贡献者协作。
+
+## License
+
+MIT。见 `LICENSE`。

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+GSE is an agent workflow skill and scaffold. Security reports may involve scripts, generated project files, host adapters, package/install behavior, signing, release trust, or documentation that could cause unsafe claims.
+
+## Supported Scope
+
+Security-relevant areas include:
+
+- Package, install, URL install, manifest integrity, signing, and verification scripts.
+- Generated host adapters and command pointers.
+- Tool permission guidance, MCP/tool routing guidance, and release trust policy.
+- Evidence, logs, and templates that could leak secrets or raw provider payloads.
+- Documentation that could cause agents to bypass owner approval, license decisions, or unsupported host boundaries.
+
+## Reporting
+
+Until a public security contact is chosen, do not publish exploit details in public issues.
+
+Use the project owner's private reporting channel. If no channel exists, record the issue privately in the maintainers' current coordination channel and mark the public release status as blocked until a contact path exists.
+
+Minimum report contents:
+
+- Affected GSE version, release label, or commit.
+- Affected file or generated artifact.
+- Reproduction steps.
+- Impact and likely affected users or hosts.
+- Whether secrets, credentials, private prompts, provider payloads, or user data are involved.
+- Suggested mitigation if known.
+
+## Handling
+
+- Do not claim a fix is verified until a focused reproduction or audit proves the changed behavior.
+- Do not publish a release if signing, package integrity, or owner trust evidence is contradicted.
+- If a public package may be affected, use `references/release-trust.md` and `assets/templates/release-trust-record.md` to record revocation, rotation, and follow-up.
+- If a project-local GSE scaffold is affected, notify the affected project session or maintainer with the exact files and validation commands.
+
+## Current Limits
+
+- No public vulnerability disclosure address has been owner-approved yet.
+- Public marketplace approval and registry publication are not verified.
+- Host-native slash-command support is not verified unless a host-specific invocation record exists.