@t275005746/gse 0.1.0 → 0.1.2

package/references/project-agent-workspace.md

@@ -1,89 +1,89 @@
-# Project Agent Workspace
-
-Use this when the user asks whether GSE can create a project-local directory for agent workflow files, hooks, skills, roles, LSP notes, MCP notes, plugins, and tool adapters.
-
-## Design Rule
-
-GSE owns `.gse/` as the portable layer. Tool-specific folders are adapters, not the source of truth.
-
-```text
-project-root/
-  .gse/
-    README.md
-    goal-map.md
-    quality-gates.md
-    tooling.md
-    learnings.md
-    agent-workspace.md
-    agents/
-      roles.md
-      dispatch.md
-    hooks/
-      README.md
-    skills/
-      README.md
-    mcp/
-      README.md
-    lsp/
-      README.md
-    plugins/
-      README.md
-    changes/
-    evidence/
-    templates/
-```
-
-## Why `.gse/` Instead of `.claude/` or `.codex/`
-
-- `.claude/`, `.codex/`, `.agents/`, and product-specific runtime folders can be useful, but they bind the project to one host.
-- `.gse/` is the neutral contract any agent can read.
-- Adapters may mirror or link from `.gse/`, but durable workflow decisions should remain in `.gse/`.
-
-## Directory Responsibilities
-
-| Path | Purpose | Required |
-|---|---|---|
-| `.gse/goal-map.md` | Current goals, priorities, risks, next slice | yes |
-| `.gse/quality-gates.md` | Verification and release gates | yes |
-| `.gse/tooling.md` | Available tools and optional adapters | yes |
-| `.gse/agent-workspace.md` | Map of local agent folders and host adapters | standard+ |
-| `.gse/agents/roles.md` | Role definitions and boundaries | standard+ |
-| `.gse/agents/dispatch.md` | How to delegate work when subagents exist | standard+ |
-| `.gse/hooks/README.md` | Hook ideas and host-specific hook mapping | enterprise |
-| `.gse/skills/README.md` | Project-local skill inventory and install notes | standard+ |
-| `.gse/mcp/README.md` | MCP servers, permissions, and setup notes | enterprise |
-| `.gse/lsp/README.md` | Indexing/LSP commands and symbol navigation notes | standard+ |
-| `.gse/plugins/README.md` | Optional plugins and runtime adapters | enterprise |
-
-## Host Adapter Pattern
-
-Use adapters only when the host supports them:
-
-- Codex: `.codex/`, Codex skills, MCP config, available subagent tools.
-- Claude Code: `.claude/`, commands, hooks, agents, MCP config.
-- Hermes or AION-like runtimes: runtime skills, worker adapters, memory, tool substrate.
-- WorkBuddy or other hosts: local docs, commands, MCP, index, and automation conventions.
-
-When an adapter is needed, write a short pointer from the host folder back to `.gse/` rather than duplicating the whole process.
-
-## Lessons Borrowed From Skill Repositories
-
-Verified local observations from `mattpocock/skills` snapshot:
-
-- Skills are organized by bucket, such as `engineering/` and `productivity/`.
-- It has a setup skill that configures per-repo assumptions before other skills rely on them.
-- It uses project docs such as `CONTEXT.md`, ADRs, issue tracker config, and a router skill.
-- It distinguishes user-invoked and model-invoked skills.
-
-GSE adopts the same principles at a workflow level: setup first, local context first, small composable roles, and a router-like goal map. GSE does not copy its Claude-specific plugin layout as a hard requirement.
-
-## Missing Areas To Keep Tracking
-
-- Secrets and permission boundaries for MCP/tools.
-- Cross-agent lock files or ownership rules for concurrent edits.
-- CI integration for quality gates.
-- Release and rollback playbooks.
-- Observability for long-running agent work: traces, cost, failed commands, retries.
-- Prompt/context budgets and compaction handoff format.
-- Drift audits for stale local skills, hooks, or generated docs.
-
+# Project Agent Workspace
+
+Use this when the user asks whether GSE can create a project-local directory for agent workflow files, hooks, skills, roles, LSP notes, MCP notes, plugins, and tool adapters.
+
+## Design Rule
+
+GSE owns `.gse/` as the portable layer. Tool-specific folders are adapters, not the source of truth.
+
+```text
+project-root/
+  .gse/
+    README.md
+    goal-map.md
+    quality-gates.md
+    tooling.md
+    learnings.md
+    agent-workspace.md
+    agents/
+      roles.md
+      dispatch.md
+    hooks/
+      README.md
+    skills/
+      README.md
+    mcp/
+      README.md
+    lsp/
+      README.md
+    plugins/
+      README.md
+    changes/
+    evidence/
+    templates/
+```
+
+## Why `.gse/` Instead of `.claude/` or `.codex/`
+
+- `.claude/`, `.codex/`, `.agents/`, and product-specific runtime folders can be useful, but they bind the project to one host.
+- `.gse/` is the neutral contract any agent can read.
+- Adapters may mirror or link from `.gse/`, but durable workflow decisions should remain in `.gse/`.
+
+## Directory Responsibilities
+
+| Path | Purpose | Required |
+|---|---|---|
+| `.gse/goal-map.md` | Current goals, priorities, risks, next slice | yes |
+| `.gse/quality-gates.md` | Verification and release gates | yes |
+| `.gse/tooling.md` | Available tools and optional adapters | yes |
+| `.gse/agent-workspace.md` | Map of local agent folders and host adapters | standard+ |
+| `.gse/agents/roles.md` | Role definitions and boundaries | standard+ |
+| `.gse/agents/dispatch.md` | How to delegate work when subagents exist | standard+ |
+| `.gse/hooks/README.md` | Hook ideas and host-specific hook mapping | enterprise |
+| `.gse/skills/README.md` | Project-local skill inventory and install notes | standard+ |
+| `.gse/mcp/README.md` | MCP servers, permissions, and setup notes | enterprise |
+| `.gse/lsp/README.md` | Indexing/LSP commands and symbol navigation notes | standard+ |
+| `.gse/plugins/README.md` | Optional plugins and runtime adapters | enterprise |
+
+## Host Adapter Pattern
+
+Use adapters only when the host supports them:
+
+- Codex: `.codex/`, Codex skills, MCP config, available subagent tools.
+- Claude Code: `.claude/`, commands, hooks, agents, MCP config.
+- Hermes or AION-like runtimes: runtime skills, worker adapters, memory, tool substrate.
+- WorkBuddy or other hosts: local docs, commands, MCP, index, and automation conventions.
+
+When an adapter is needed, write a short pointer from the host folder back to `.gse/` rather than duplicating the whole process.
+
+## Lessons Borrowed From Skill Repositories
+
+Verified local observations from `mattpocock/skills` snapshot:
+
+- Skills are organized by bucket, such as `engineering/` and `productivity/`.
+- It has a setup skill that configures per-repo assumptions before other skills rely on them.
+- It uses project docs such as `CONTEXT.md`, ADRs, issue tracker config, and a router skill.
+- It distinguishes user-invoked and model-invoked skills.
+
+GSE adopts the same principles at a workflow level: setup first, local context first, small composable roles, and a router-like goal map. GSE does not copy its Claude-specific plugin layout as a hard requirement.
+
+## Missing Areas To Keep Tracking
+
+- Secrets and permission boundaries for MCP/tools.
+- Cross-agent lock files or ownership rules for concurrent edits.
+- CI integration for quality gates.
+- Release and rollback playbooks.
+- Observability for long-running agent work: traces, cost, failed commands, retries.
+- Prompt/context budgets and compaction handoff format.
+- Drift audits for stale local skills, hooks, or generated docs.
+

package/references/project-bootstrap.md

@@ -1,122 +1,122 @@
-# Project Bootstrap
-
-Use this when initializing GSE in a project.
-
-Use `references/adoption-recipes.md` when choosing between fresh install, existing repo adoption, GSE update, or host adapter adoption paths.
-
-## Modes
-
-- `auto`: default mode; chooses a scaffold from project files, scripts, CI, host folders, and runtime/tooling signals.
-- `lite`: minimal workflow files for small tasks or small projects.
-- `standard`: adds project-local agent workspace files for durable agent-assisted development.
-- `enterprise`: adds hooks, MCP, plugins, release, incident, and audit placeholders for large or long-running projects.
-
-## Minimal `.gse/` Files
-
-```text
-.gse/
-  README.md
-  state.json
-  project-profile.md
-  goal-map.md
-  goals/
-    README.md
-  quality-gates.md
-  tooling.md
-  learnings.md
-  changes/
-  evidence/
-    index.jsonl
-  templates/
-```
-
-## Standard Agent Workspace Files
-
-See `project-agent-workspace.md` for responsibilities.
-
-```text
-.gse/
-  agent-workspace.md
-  agents/
-    roles.md
-    dispatch.md
-  skills/
-    README.md
-  lsp/
-    README.md
-```
-
-## Enterprise Files
-
-```text
-.gse/
-  hooks/README.md
-  mcp/README.md
-  plugins/README.md
-  release.md
-  incident-review.md
-  audit.md
-```
-
-## Host Adapter Files
-
-When `enterprise` mode is selected and host folders already exist, `init-project.mjs` can add thin adapters such as:
-
-```text
-.codex/gse-adapter.md
-.claude/gse-adapter.md
-```
-
-These files point back to `.gse/` and must not duplicate the portable goal map, quality gates, or evidence log.
-
-For new host command/pointer adapters, prefer:
-
-```bash
-node <skill-dir>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
-```
-
-The older `.codex/gse-adapter.md` and `.claude/gse-adapter.md` files remain compatibility pointers for existing scaffold and fixture coverage.
-
-## Recommended Command
-
-```bash
-node <skill-dir>/scripts/init-project.mjs --target <project-root>
-```
-
-This uses `--mode auto`. Pass `--mode lite`, `--mode standard`, or `--mode enterprise` when the project owner wants a specific scaffold.
-
-The script should not overwrite existing files unless `--force` is passed.
-
-## Bootstrap Smoke
-
-Use this after changing scaffold behavior or before trusting a packaged GSE skill:
-
-```bash
-node <skill-dir>/scripts/audit-project.mjs --root <skill-dir>
-```
-
-This verifies `lite`, `standard`, `enterprise`, and representative `auto` scaffold selection in temporary directories and checks rerun safety. It does not certify arbitrary real repositories, package installs, CI, or fresh-session acceptance.
-
-## AGENTS.md Integration
-
-Add a short project rule only with explicit approval:
-
-```markdown
-## GSE Workflow
-
-This project follows GSE (Goal-Spec-Evidence Engineering). Start meaningful work by reading `.gse/README.md`, bind non-trivial tasks to `.gse/goal-map.md`, and finish with evidence in `.gse/evidence/` or the project-specific evidence log.
-```
-
-## Bootstrap Acceptance
-
-- `.gse/README.md` exists.
-- `.gse/state.json` exists and records mode, phase, current slice status, tool statuses, last evidence, and residual risks.
-- `.gse/project-profile.md` exists and can capture project-specific standards, commands, tools, and permissions.
-- Goal map has a North Star and Current Focus section.
-- `.gse/evidence/index.jsonl` exists and contains at least one machine-readable adoption or slice record.
-- `.gse/goals/README.md` exists so large projects can place module-level goal details outside the root goal map.
-- Quality gates list at least universal, code, UI, release, and learning gates.
-- Tooling file records available and optional tools.
-- Standard mode records project-local agent workspace files.
-- Enterprise mode records hooks, MCP, plugins, release, incident, and audit placeholders.
-- Enterprise auto mode writes compatibility host adapter files for existing `.codex/` or `.claude/` folders; command adapters for broader hosts use `generate-command-adapter.mjs`.
+# Project Bootstrap
+
+Use this when initializing GSE in a project.
+
+Use `references/adoption-recipes.md` when choosing between fresh install, existing repo adoption, GSE update, or host adapter adoption paths.
+
+## Modes
+
+- `auto`: default mode; chooses a scaffold from project files, scripts, CI, host folders, and runtime/tooling signals.
+- `lite`: minimal workflow files for small tasks or small projects.
+- `standard`: adds project-local agent workspace files for durable agent-assisted development.
+- `enterprise`: adds hooks, MCP, plugins, release, incident, and audit placeholders for large or long-running projects.
+
+## Minimal `.gse/` Files
+
+```text
+.gse/
+  README.md
+  state.json
+  project-profile.md
+  goal-map.md
+  goals/
+    README.md
+  quality-gates.md
+  tooling.md
+  learnings.md
+  changes/
+  evidence/
+    index.jsonl
+  templates/
+```
+
+## Standard Agent Workspace Files
+
+See `project-agent-workspace.md` for responsibilities.
+
+```text
+.gse/
+  agent-workspace.md
+  agents/
+    roles.md
+    dispatch.md
+  skills/
+    README.md
+  lsp/
+    README.md
+```
+
+## Enterprise Files
+
+```text
+.gse/
+  hooks/README.md
+  mcp/README.md
+  plugins/README.md
+  release.md
+  incident-review.md
+  audit.md
+```
+
+## Host Adapter Files
+
+When `enterprise` mode is selected and host folders already exist, `init-project.mjs` can add thin adapters such as:
+
+```text
+.codex/gse-adapter.md
+.claude/gse-adapter.md
+```
+
+These files point back to `.gse/` and must not duplicate the portable goal map, quality gates, or evidence log.
+
+For new host command/pointer adapters, prefer:
+
+```bash
+node <skill-dir>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
+```
+
+The older `.codex/gse-adapter.md` and `.claude/gse-adapter.md` files remain compatibility pointers for existing scaffold and fixture coverage.
+
+## Recommended Command
+
+```bash
+node <skill-dir>/scripts/init-project.mjs --target <project-root>
+```
+
+This uses `--mode auto`. Pass `--mode lite`, `--mode standard`, or `--mode enterprise` when the project owner wants a specific scaffold.
+
+The script should not overwrite existing files unless `--force` is passed.
+
+## Bootstrap Smoke
+
+Use this after changing scaffold behavior or before trusting a packaged GSE skill:
+
+```bash
+node <skill-dir>/scripts/audit-project.mjs --root <skill-dir>
+```
+
+This verifies `lite`, `standard`, `enterprise`, and representative `auto` scaffold selection in temporary directories and checks rerun safety. It does not certify arbitrary real repositories, package installs, CI, or fresh-session acceptance.
+
+## AGENTS.md Integration
+
+Add a short project rule only with explicit approval:
+
+```markdown
+## GSE Workflow
+
+This project follows GSE (Goal-Spec-Evidence Engineering). Start meaningful work by reading `.gse/README.md`, bind non-trivial tasks to `.gse/goal-map.md`, and finish with evidence in `.gse/evidence/` or the project-specific evidence log.
+```
+
+## Bootstrap Acceptance
+
+- `.gse/README.md` exists.
+- `.gse/state.json` exists and records mode, phase, current slice status, tool statuses, last evidence, and residual risks.
+- `.gse/project-profile.md` exists and can capture project-specific standards, commands, tools, and permissions.
+- Goal map has a North Star and Current Focus section.
+- `.gse/evidence/index.jsonl` exists and contains at least one machine-readable adoption or slice record.
+- `.gse/goals/README.md` exists so large projects can place module-level goal details outside the root goal map.
+- Quality gates list at least universal, code, UI, release, and learning gates.
+- Tooling file records available and optional tools.
+- Standard mode records project-local agent workspace files.
+- Enterprise mode records hooks, MCP, plugins, release, incident, and audit placeholders.
+- Enterprise auto mode writes compatibility host adapter files for existing `.codex/` or `.claude/` folders; command adapters for broader hosts use `generate-command-adapter.mjs`.

package/references/project-guards.md

@@ -0,0 +1,52 @@
+# Project Guards
+
+Project guards are reusable preflight rules promoted from repeated project lessons.
+
+They sit between learning notes and hard quality gates:
+
+```text
+lesson -> project guard -> quality gate -> script/test/skill update
+```
+
+Use guards when a mistake is likely to recur across sessions, but the rule still needs project context.
+
+## Guard File
+
+Default project-local path:
+
+```text
+.gse/project-guards.md
+```
+
+The file uses a small table so humans can edit it and scripts can audit it:
+
+| ID | Guard | Severity | Trigger | Check | Status |
+|---|---|---|---|---|---|
+| UTF8-DOC | Use UTF-8-safe readers for Chinese or multilingual docs before judging mojibake. | high | Chinese docs or encoding complaint | Read with Node UTF-8 or another UTF-8-safe viewer; run the project encoding check when docs changed. | active |
+
+## Default Guard Set
+
+- `WIN-SHELL`: shell syntax must match the active host.
+- `SPARSE-GIT`: sparse checkout must be checked before staging generated workflow folders.
+- `UTF8-DOC`: multilingual docs need UTF-8-safe reads and encoding checks.
+- `EVIDENCE-STALE`: stale or broken evidence is a preflight issue.
+- `UI-EVIDENCE`: UI/browser downgrades must be labeled explicitly.
+- `SUBAGENT-HONEST`: subagent dispatch claims require real host evidence.
+- `SYNC-NO-INTERRUPT`: cross-thread GSE upgrade sync must not interrupt a running project session.
+
+## Continue Behavior
+
+`/gse continue` reads `.gse/project-guards.md` when present and returns an active guard summary in the compact packet.
+
+Missing guard files are a warning for mature projects, not a hard failure. Broken state or evidence remains the hard preflight failure.
+
+## Promotion
+
+- First occurrence: record in `.gse/learnings.md`.
+- Second occurrence: update a checklist, template, or guard candidate.
+- Third occurrence: promote to `.gse/project-guards.md` or `.gse/quality-gates.md`.
+- Fifth occurrence: automate as a script, test, or skill update.
+
+Do not hardcode product-specific behavior into the GSE skill. AION and MuseFlow can supply examples and evidence, but project guards must stay generic.
+
+Cross-thread sync is a guard-sensitive action: prefer evidence records, release notes, or owner action notes. Send a message to another active project session only when it is idle or the owner explicitly asks for immediate sync.

package/references/project-profile.md

@@ -1,57 +1,57 @@
-# Project Profile
-
-Use this when a project has its own development standards, commands, tool connections, CI, MCP servers, LSP/index setup, release process, security rules, or agent-host conventions.
-
-## Principle
-
-Project-local rules override generic GSE defaults. GSE should adapt to the project, not flatten the project into a generic workflow.
-
-## Discovery Order
-
-Read only what is relevant to the task and risk level:
-
-1. Agent rules: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, or host equivalents.
-2. Project docs: README, CONTRIBUTING, CODING_STANDARDS, architecture docs, ADRs, `CONTEXT.md`.
-3. Commands and scripts: `package.json`, `Makefile`, task runners, CI workflows, test config.
-4. Tooling connections: MCP config, browser/Playwright config, LSP/index config, deployment config, observability config.
-5. Secrets and permissions: `.env.example`, secret docs, write-capable tools, destructive commands.
-6. Existing GSE files: `.gse/project-profile.md`, `.gse/tooling.md`, `.gse/quality-gates.md`.
-
-Avoid reading generated output, large logs, lockfiles, caches, screenshots, or archives unless the current task needs them.
-
-## What To Capture
-
-Keep `.gse/project-profile.md` short and factual:
-
-- Product or system identity.
-- Repository type and main languages/frameworks.
-- Development commands and focused verification commands.
-- Coding standards and formatting rules.
-- Testing strategy and required gates.
-- Tool connections: MCP, LSP/index, browser automation, CI, deploy, observability.
-- Model routing: project-approved providers, model/tool ids, capability fit, cost/latency expectations, privacy limits, and fallback policy.
-- Agent host adapters: Codex, Claude Code, Hermes/AION-style runtime, WorkBuddy, or other hosts; use `references/compatibility.md` for support status labels.
-- Security and permission boundaries.
-- Release and rollback expectations.
-- Known gotchas.
-
-## Conflict Rules
-
-- User instruction in the current conversation wins.
-- Project rules beat GSE generic defaults.
-- More specific docs beat broad docs when they clearly apply to the current subsystem.
-- If two project rules conflict, surface the conflict before editing.
-- Never invent tool availability. Mark unverified connections as `unknown` until tested or documented.
-
-## Refresh Triggers
-
-Use `references/drift-audit.md` when current project facts may have diverged from recorded profile, tooling, host, release, or permission assumptions.
-
-Refresh `.gse/project-profile.md` when:
-
-- The user says a tool/config/standard exists but GSE cannot see it.
-- A command fails because the wrong package manager, shell, or service was assumed.
-- CI/test/deploy config changes.
-- New MCP, LSP, browser, worker, model, or plugin connections are added.
-- A recurring issue appears in evidence or incident reviews.
-
+# Project Profile
+
+Use this when a project has its own development standards, commands, tool connections, CI, MCP servers, LSP/index setup, release process, security rules, or agent-host conventions.
+
+## Principle
+
+Project-local rules override generic GSE defaults. GSE should adapt to the project, not flatten the project into a generic workflow.
+
+## Discovery Order
+
+Read only what is relevant to the task and risk level:
+
+1. Agent rules: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, or host equivalents.
+2. Project docs: README, CONTRIBUTING, CODING_STANDARDS, architecture docs, ADRs, `CONTEXT.md`.
+3. Commands and scripts: `package.json`, `Makefile`, task runners, CI workflows, test config.
+4. Tooling connections: MCP config, browser/Playwright config, LSP/index config, deployment config, observability config.
+5. Secrets and permissions: `.env.example`, secret docs, write-capable tools, destructive commands.
+6. Existing GSE files: `.gse/project-profile.md`, `.gse/tooling.md`, `.gse/quality-gates.md`.
+
+Avoid reading generated output, large logs, lockfiles, caches, screenshots, or archives unless the current task needs them.
+
+## What To Capture
+
+Keep `.gse/project-profile.md` short and factual:
+
+- Product or system identity.
+- Repository type and main languages/frameworks.
+- Development commands and focused verification commands.
+- Coding standards and formatting rules.
+- Testing strategy and required gates.
+- Tool connections: MCP, LSP/index, browser automation, CI, deploy, observability.
+- Model routing: project-approved providers, model/tool ids, capability fit, cost/latency expectations, privacy limits, and fallback policy.
+- Agent host adapters: Codex, Claude Code, Hermes/AION-style runtime, WorkBuddy, or other hosts; use `references/compatibility.md` for support status labels.
+- Security and permission boundaries.
+- Release and rollback expectations.
+- Known gotchas.
+
+## Conflict Rules
+
+- User instruction in the current conversation wins.
+- Project rules beat GSE generic defaults.
+- More specific docs beat broad docs when they clearly apply to the current subsystem.
+- If two project rules conflict, surface the conflict before editing.
+- Never invent tool availability. Mark unverified connections as `unknown` until tested or documented.
+
+## Refresh Triggers
+
+Use `references/drift-audit.md` when current project facts may have diverged from recorded profile, tooling, host, release, or permission assumptions.
+
+Refresh `.gse/project-profile.md` when:
+
+- The user says a tool/config/standard exists but GSE cannot see it.
+- A command fails because the wrong package manager, shell, or service was assumed.
+- CI/test/deploy config changes.
+- New MCP, LSP, browser, worker, model, or plugin connections are added.
+- A recurring issue appears in evidence or incident reviews.
+