@t275005746/gse 0.1.0

package/examples/cli-tool/AGENTS.md

@@ -0,0 +1,5 @@
+# CLI Tool Fixture Rules
+
+- Preserve package scripts and release notes when adopting GSE.
+- Treat `bin` entries and publish scripts as documented until a focused smoke runs.
+- Do not claim package publishing, npm access, shell completion, or global install support without evidence.

package/examples/cli-tool/README.md

@@ -0,0 +1,12 @@
+# cli-tool fixture
+
+Purpose: representative command-line package shape for GSE adoption tests.
+
+Suggested checks:
+
+- Run `node <gse>/scripts/discover-project-profile.mjs --target <fixture> --json`.
+- Confirm package scripts are documented, not verified.
+- Confirm CLI smoke, package validation, and release/publish signals are discovered from `package.json`.
+- Confirm host capabilities remain `unknown` unless a host-specific adapter or current-session evidence exists.
+
+No install or package publish is required for structural fixture use.

package/examples/cli-tool/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "gse-cli-tool-fixture",
+  "version": "0.0.0-fixture",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "gse-fixture": "./src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "smoke": "node ./src/cli.mjs --help",
+    "build": "tsc -p tsconfig.json",
+    "release:dry-run": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "eslint": "^9.0.0"
+  }
+}

package/examples/small-app/.env.example

@@ -0,0 +1,2 @@
+PUBLIC_API_BASE_URL=http://localhost:3000
+FEATURE_FLAG_EXAMPLE=false

package/examples/small-app/.github/workflows/ci.yml

@@ -0,0 +1,8 @@
+name: fixture-ci
+on: [push]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo "fixture only; commands are documented, not verified"

package/examples/small-app/AGENTS.md

@@ -0,0 +1,5 @@
+# Fixture Agent Rules
+
+- Use `.gse/project-profile.md` when present.
+- Keep changes small and verified.
+- Do not commit secrets, lockfiles, caches, screenshots, or build outputs from this fixture.

package/examples/small-app/README.md

@@ -0,0 +1,12 @@
+# small-app fixture
+
+Purpose: representative small web app shape for GSE bootstrap and project-profile discovery tests.
+
+Suggested checks:
+
+- Run `node <gse>/scripts/discover-project-profile.mjs --target <fixture> --json`.
+- Confirm package scripts are documented, not verified.
+- Confirm browser/Playwright and CI are detected from config files.
+- Confirm `.env.example` is treated as secrets documentation without reading real secrets.
+
+No install is required for structural fixture use.

package/examples/small-app/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "gse-small-app-fixture",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "vite": "latest"
+  },
+  "devDependencies": {
+    "@playwright/test": "latest",
+    "eslint": "latest",
+    "prettier": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  }
+}

package/examples/small-app/playwright.config.ts

@@ -0,0 +1,4 @@
+export default {
+  testDir: "./tests/e2e",
+  use: { baseURL: "http://localhost:5173" },
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@t275005746/gse",
+  "version": "0.1.0",
+  "description": "Goal-Spec-Evidence Engineering workflow skill for long-running agent-assisted software projects.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://gatehub.top/",
+  "bin": {
+    "gse": "scripts/gse.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "SECURITY.md",
+    "SUPPORT.md",
+    ".github",
+    ".gse/README.md",
+    ".gse/project-profile.md",
+    ".gse/quality-gates.md",
+    ".gse/gse-development-protocol.md",
+    ".gse/state.json",
+    ".gse/releases",
+    "agents",
+    "assets",
+    "examples",
+    "references",
+    "scripts"
+  ],
+  "scripts": {
+    "audit:npm": "node scripts/audit-npm-package-metadata.mjs --root . --json",
+    "audit:npm-install": "node scripts/audit-npm-tarball-install.mjs --root . --json",
+    "audit:npm-publish": "node scripts/audit-npm-publish-dry-run.mjs --root . --json",
+    "validate": "node scripts/validate-gse.mjs --root . --json",
+    "pack:dry-run": "npm pack --dry-run --json"
+  },
+  "keywords": [
+    "gse",
+    "goal-spec-evidence",
+    "agentic-engineering",
+    "ai-coding-agent",
+    "spec-driven-development",
+    "sdd",
+    "evidence-gates",
+    "workflow"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/references/adoption-recipes.md

@@ -0,0 +1,171 @@
+# Adoption Recipes
+
+Use this when applying GSE to a project or updating an existing GSE installation.
+
+These recipes are host-neutral. They do not certify arbitrary repositories, install external tools, publish GSE, or verify host runtime capabilities. Treat project and host capabilities as `unknown` until checked in that project/session.
+
+## Recipe 1: Fresh Project Install
+
+Use when a project has no `.gse/` folder yet.
+
+Steps:
+
+1. Read project rules first: `AGENTS.md`, `CLAUDE.md`, README, or equivalent.
+2. Choose mode from `references/task-levels.md` and `references/project-bootstrap.md`: `lite`, `standard`, or `enterprise`.
+3. Run:
+
+```text
+node <gse-skill>/scripts/init-project.mjs --target <project-root> --mode <mode>
+```
+
+4. Inspect generated `.gse/state.json`, `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/quality-gates.md`, `.gse/tooling.md`, and `.gse/evidence/index.jsonl`.
+5. Record project-specific commands, standards, permissions, and owners in `.gse/project-profile.md`.
+6. Run the smallest project verification that proves the install is usable, such as checking files exist and reading `.gse/README.md`.
+   Prefer the target doctor when available:
+
+```text
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+```
+
+7. Record residual risk: commands, CI, browser, MCP, LSP, subagents, models, and release paths remain `unknown` until executed.
+
+Evidence status: `result` when files exist; `verified` only after focused project inspection or smoke proves the generated workflow is usable.
+
+## Recipe 2: Existing Repo Adoption
+
+Use when a repository already has rules, scripts, CI, host folders, or partial `.gse/` files.
+
+Steps:
+
+1. Read project rules and existing workflow docs before generating anything.
+2. Run discovery without writing:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+3. Treat discovered scripts/configs as `documented`, not `verified`, until the commands actually run.
+4. If `.gse/project-profile.md` already exists, do not overwrite it without explicit `--force` and a reason. Do not overwrite existing project workflow files just because GSE has defaults.
+5. If writing is approved, use:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --write
+```
+
+6. Preserve project-specific standards, host adapters, existing evidence logs, and owner decisions.
+7. Record whether adoption is `result`, `verified`, or `accepted` using `references/evidence-taxonomy.md`.
+
+Evidence status: `verified` for controlled fixture behavior when `scripts/audit-adoption.mjs` passes; real repos need project-specific evidence.
+
+## Recipe 3: Update Existing GSE
+
+Use when a project already follows GSE and the skill or project-local `.gse/` files need an update.
+
+Steps:
+
+1. Read `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/current-slice.md` if present, and host adapter notes.
+   Prefer `.gse/state.json` and `.gse/evidence/index.jsonl` when present because they are the machine-readable continuation state.
+2. Identify whether the update affects templates, scripts, host adapters, quality gates, release/recovery, or project rules.
+3. Preserve local project decisions. Do not replace project `.gse/` files with skill defaults unless the project owner approves.
+4. Run skill validation after updating the skill package:
+
+```text
+node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
+```
+
+5. Run project-local validation or smoke for the affected workflow.
+   For read-only workflow drift checks, run:
+
+```text
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+```
+
+If the project predates `.gse/state.json` and `.gse/evidence/index.jsonl`, add only the missing machine-readable continuation files:
+
+```text
+node <gse-skill>/scripts/update-project-state.mjs --target <project-root>
+```
+
+6. Record changed files, migration/rollback notes, evidence status, residual risks, and next action in the project evidence log.
+
+Evidence status: `verified` only when the project-local update path and affected workflow have focused evidence.
+
+## Recipe 4: Host Adapter Adoption
+
+Use when a project needs Codex, Claude Code, Hermes/AION-style runtime, WorkBuddy, Copilot/Gemini-style, or custom host pointers.
+
+Steps:
+
+1. Read `references/compatibility.md` and `references/host-adapters.md`.
+2. Generate short command/pointer adapters only when the host has a real adapter location:
+
+```text
+node <gse-skill>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
+```
+
+`scripts/generate-host-adapter.mjs` is a legacy fixture helper for the older Codex/Claude markdown adapter smoke. Prefer `generate-command-adapter.mjs` for new project adoption.
+
+3. Keep `.gse/` as the source of truth. Do not copy goal maps, quality gates, or evidence into host folders.
+4. Mark host capabilities as `verified`, `documented`, `unknown`, or `unavailable` based on current evidence.
+5. Run `scripts/audit-host-adapters.mjs` for GSE fixture coverage, then run project-specific inspection for the target project.
+
+Evidence status: fixture generation can be `verified`; actual host runtime tools remain project/session-specific.
+
+## Recipe 5: CLI Or Package Project Adoption
+
+Use when a project is primarily a command-line tool, reusable package, SDK, plugin, or library rather than a web app.
+
+Steps:
+
+1. Read package docs and project rules before changing workflow files: `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, package manifest, and release notes if present.
+2. Run discovery first:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+3. Treat `bin` entries, package scripts, publish commands, signing, registry, and shell integration as `documented` or `unknown` until a focused smoke proves them.
+4. Preserve package metadata, release notes, compatibility policy, and existing publish/rollback instructions.
+5. Prefer a small command smoke before broader tests, such as `npm run smoke`, `node ./bin/<name> --help`, `npm pack --dry-run`, or the project equivalent.
+6. Record exit-code behavior, changed files, package artifacts intentionally ignored, residual release risk, and next action.
+
+Evidence status: fixture coverage can be `verified`; real package install, registry access, publish permissions, global install, and shell completion require project-specific evidence.
+
+## Adoption Record
+
+Use this compact record in `.gse/evidence/` or the project evidence log:
+
+```text
+Adoption recipe:
+Project path:
+Mode or host:
+Project rules read:
+Commands run:
+Files created or changed:
+Preserved project-specific rules:
+Host/tool statuses:
+Validation evidence:
+Evidence status: result | verified | accepted | not ready
+Residual risk:
+Next action:
+```
+
+For real target-project evidence, use `assets/templates/target-adoption-evidence.md`. Keep discovered scripts and configs as `documented` until executed, and keep `Accepted by: not accepted` unless a real acceptance gate ran.
+
+Use `assets/templates/acceptance-execution-packet.md` before writing project-local `.gse/` artifacts or claiming owner-approved adoption acceptance.
+
+## Verification Commands
+
+Use only the commands that match the recipe and risk:
+
+```text
+node <gse-skill>/scripts/audit-project.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-adoption.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-command-adapters.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-host-adapters.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-fixtures.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
+```
+
+These commands verify GSE fixtures and skill readiness. They do not certify arbitrary production repositories. Real adoption still needs project-specific inspection, focused smokes, and evidence.

package/references/agent-roles.md

@@ -0,0 +1,49 @@
+# Agent Roles
+
+Use roles to make multi-agent work predictable.
+
+## Coordinator
+
+Owns scope, task level, context selection, final integration, and final answer.
+
+Never delegates final judgment.
+
+## Product Analyst
+
+Clarifies user outcome, pain, audience, competitive baseline, and priority.
+
+## Architect
+
+Defines state, data flow, module boundaries, contracts, risks, and rollback.
+
+## Code Locator
+
+Read-only. Finds files, symbols, call chains, existing tests, and local patterns.
+
+## Builder
+
+Implements a bounded slice. Avoids unrelated refactors.
+
+## Reviewer
+
+Checks correctness, regressions, architecture drift, security, and missing tests using `references/review.md`.
+
+## QA
+
+Runs focused verification, browser smoke, API smoke, or screenshot checks.
+
+## Docs/Evidence
+
+Writes evidence, changelog notes, ADR links, and learning entries. Does not modify implementation unless explicitly assigned.
+
+## Dispatch Rules
+
+- Use real subagent tools only when exposed by the current host.
+- Give each agent a role, files allowed, expected output, and forbidden actions. Use `assets/templates/dispatch-packet.md` when the assignment needs durable boundaries or evidence.
+- Avoid parallel writes to the same files.
+- If subagents are unavailable, execute roles sequentially in the main session and say so.
+
+## File Ownership
+
+Use `references/file-ownership.md` before assigning write access, running parallel implementation, or editing in a dirty worktree. Keep locator, reviewer, and QA roles read-only unless explicitly assigned otherwise.
+

package/references/architecture-health.md

@@ -0,0 +1,101 @@
+# Architecture Health
+
+Use this when a change may affect the long-term shape of a project, not only the immediate behavior. Architecture health checks look for structural drift that can make future work slower, riskier, or harder for agents to understand.
+
+## Trigger Conditions
+
+Run an architecture health scan when any of these are true:
+
+- A change crosses module boundaries, package boundaries, runtime boundaries, product boundaries, or host adapter boundaries.
+- A new subsystem, provider, model route, worker, storage layer, queue, browser/runtime path, or deployment path is added.
+- Repeated bugs suggest hidden coupling, unclear ownership, duplicated logic, or a missing source of truth.
+- A dependency, security boundary, permission model, migration, release path, or rollback path changes.
+- Performance, resilience, cancellation, retry, state recovery, or observability behavior is material to the slice.
+- Project docs, generated artifacts, code, and .gse/ records disagree about the intended design.
+
+Do not run a broad scan for tiny local edits unless the edit touches a structural boundary.
+
+## Scope Levels
+
+Pick the smallest scan that can prove the risk is understood.
+
+| Level | Use when | Minimum evidence |
+|---|---|---|
+| Lightweight local scan | One file, one module, one adapter, or one narrow workflow changed | Relevant files, nearest tests/checks, project rules that govern the area |
+| Subsystem scan | A feature crosses modules, storage/state, API/UI, worker/runtime, or tool boundaries | Call flow, data ownership, source-of-truth records, focused verification |
+| Broad architecture review | Large refactor, new platform capability, release/migration risk, recurring failures, or uncertain ownership | Architecture docs, ADRs, project profile, dependency/release notes, evidence and follow-up slices |
+
+## Scan Axes
+
+### Module Boundaries
+
+- Are module boundaries, package boundaries, runtime boundaries, and host adapter boundaries still clear?
+- Did the change import across layers in a way the project does not already allow?
+- Is shared behavior placed in the right owner instead of copied into callers?
+
+### Coupling And Cohesion
+
+- Did the change create tight coupling between UI, API, worker, storage, tools, models, or host-specific adapters?
+- Can a future agent change one concern without understanding unrelated concerns?
+- Are abstractions justified by repeated complexity or existing project patterns?
+
+### Source Of Truth Drift
+
+- Is there one source of truth for goals, specs, state, memory, routing, configuration, and evidence?
+- Do docs, code, scripts, templates, generated files, and .gse/ records agree?
+- Are compatibility names or legacy internal names contained behind adapters rather than exposed as product truth?
+
+### Dependency And Security Risk
+
+- Did dependencies, provider SDKs, MCP/tool integrations, or browser/runtime permissions change?
+- Are dependency and security assumptions verified, documented, or explicitly unknown?
+- Are secrets, raw provider payloads, hidden reasoning, and privileged tool traces excluded from user-visible or committed outputs?
+
+### Ownership And Change Control
+
+- Which module, team, role, or agent owns the changed behavior?
+- Are file ownership and multi-agent lock rules clear enough to prevent overlapping edits?
+- Does the change need an ADR, project-profile update, or future release note?
+
+### Performance And Resilience
+
+- Could the design add latency, heavy context loading, unnecessary worker paths, repeated browser loops, or expensive model routes?
+- Are cancellation, retry, timeout, recovery, idempotency, and duplicate prevention considered where relevant?
+- Is observability enough to diagnose failure without leaking sensitive data?
+
+### Migration And Release Impact
+
+- Does the change affect install, upgrade, data migration, backward compatibility, rollback, or release acceptance?
+- Are migration and release risks captured as decisions or follow-up slices rather than hidden assumptions?
+- Is the verification scope strong enough for the release risk?
+
+## Output Format
+
+Keep the output concise. Link to evidence instead of pasting long logs.
+
+```text
+Scan scope:
+Findings:
+Risks:
+Decisions needed:
+Follow-up slices:
+Evidence:
+```
+
+## Classification Rules
+
+- Findings are observed facts from code, docs, scripts, tests, or runtime behavior.
+- Risks are plausible future failures or maintenance costs that the current evidence does not eliminate.
+- Decisions needed are architecture choices that require owner, user, or project-standard confirmation.
+- Follow-up slices are bounded implementation or documentation steps that can be verified later.
+
+Do not label a guess as a finding. If evidence is indirect, record it as a risk or assumption and choose a follow-up slice.
+
+## Integration
+
+- Use references/review.md for the review axes and severity language.
+- Use references/quality-gates.md to decide whether architecture health is required for the task risk.
+- Use references/file-ownership.md when ownership, dirty worktree, or multi-agent overlap is unclear.
+- Use references/project-profile.md and project architecture docs as the source of project-specific standards.
+- Use references/release.md when architecture risk affects migration, rollback, compatibility, changelog/release notes, or release acceptance.
+- Use references/evidence-taxonomy.md to classify the final claim as result, verified, or accepted.

package/references/benchmark-audit.md

@@ -0,0 +1,73 @@
+# Benchmark Audit
+
+Use this when improving GSE itself: changing the GSE skill, its scripts, templates, references, project scaffold, or development goals.
+
+## Purpose
+
+GSE development must proactively find workflow gaps. Do not wait for the user to discover missing requirements through manual testing.
+
+Run this audit against verified local skills, project files, tool help, official docs when available, and focused experiments. Label design judgments separately from verified facts.
+
+## Benchmark Sources
+
+Use the best available sources for the current host:
+
+- Local GSE files under `.gse/` or the skill folder.
+- Installed workflow skills: Comet, OpenSpec, Superpowers-style skills, agentic-engineering, subagent-driven-development, TDD, code review, self-improvement, QA, CI/CD.
+- Public or local skill repositories when explicitly referenced or already cloned, such as `mattpocock/skills`.
+- Project rules only when GSE is being tested inside a real project: `AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, ADRs, issue tracker docs, CI config, test scripts.
+- Official tool docs only when needed for a drift-prone claim.
+
+## GSE Development Audit Matrix
+
+Score each area as `missing`, `thin`, `usable`, or `strong`.
+
+| Area | Questions |
+|---|---|
+| Setup | Can a new agent install or initialize GSE without guessing? |
+| Router | Is there a clear map from user intent to GSE references, scripts, and modes? |
+| Goal Map | Are GSE's north star, current priority, risks, and next slice visible? |
+| Domain Model | Is shared language captured, challenged, and updated? |
+| Specs | Are GSE change outcome, scope, non-goals, contracts, and acceptance explicit? |
+| Task Slicing | Are tasks vertical, independently verifiable, and sized by risk? |
+| Tool Acceleration | Are search, LSP/index, browser, API, MCP, and CI tools recorded with fallbacks? |
+| Multi-Agent | Are roles, dispatch packets, file ownership, review gates, and no-fake-delegation rules clear? |
+| Implementation | Does GSE development preserve skill patterns and avoid unrelated expansion? |
+| Testing | Are focused tests, TDD, smoke, regression, and UI verification rules present? |
+| Review | Are spec compliance and code quality reviewed separately? |
+| Evidence | Is GSE change evidence recorded with commands and residual risk? |
+| Release | Are migration, rollout, rollback, smoke, and known-risk steps defined? |
+| Incident | Is there a path for failures, postmortems, and prevention gates? |
+| Learning | Are reusable lessons promoted into rules, gates, or templates? |
+| Context Hygiene | Are handoff, compaction, stale-context, and token-budget rules defined? |
+| Adapter Drift | Are host-specific GSE adapters prevented from diverging from the portable source of truth? |
+| Security | Are secrets, permissions, destructive tools, and external services bounded? |
+| Observability | Are traces, cost, retries, failures, and long-running state captured when relevant? |
+
+## Required Output
+
+```text
+Outcome:
+Benchmark sources:
+Strong areas:
+Gaps:
+Design goal updates:
+Next action:
+Evidence:
+```
+
+## Design Goal Update Rules
+
+- Add a goal only when it prevents a real failure mode or improves repeatable quality.
+- Prefer a small artifact or script over a large prose rule.
+- Keep hard prerequisites minimal; record optional adapters separately.
+- Turn recurring user corrections into audits, gates, or templates.
+- If a benchmark is tool-specific, extract the portable principle before adding it to GSE.
+- For non-trivial GSE changes, use `references/forward-test.md` to decide whether structural smoke, fixture forward test, or fresh-session forward test is required.
+
+## Current Known GSE Gaps
+
+- GSE has project scoring, bootstrap smoke, target doctor, command adapters, release gates, evidence taxonomy, quality gates, and final-form progress audits. Keep this section current when a gap is closed so future agents do not chase stale work.
+- Host adapter pointer templates are verified through `scripts/generate-command-adapter.mjs` and `scripts/audit-command-adapters.mjs`; older `generate-host-adapter.mjs` coverage is legacy fixture compatibility, not the preferred adoption route.
+- Remaining final-form gaps are owner/external evidence gates: public repository settings, public CI run, public security contact, registry publication, marketplace approval, native slash-command evidence, and other host runtime invocation.
+- Local future-hardening candidates should come from fresh benchmark evidence, not from this historical list.