@t275005746/gse 0.1.0 → 0.1.2

package/references/design-basis.md

@@ -1,38 +1,38 @@
-# GSE Design Basis
-
-This file separates verified sources from design judgment.
-
-## Verified Local Sources
-
-- `skill-creator` requires a concise `SKILL.md`, optional `references/`, `scripts/`, and `assets/`, with progressive disclosure and validation.
-- `agentic-engineering` defines eval-first execution, agent-sized decomposition, model routing, and review focus for AI-generated code.
-- `subagent-driven-development` defines fresh subagents per task, explicit roles, spec review, code quality review, and never faking delegation.
-- `comet` combines OpenSpec and Superpowers through open, design, build, verify, archive phases, with hotfix/tweak presets and state files.
-- `openspec-propose` creates proposal, design, specs, and tasks as change artifacts.
-- `self-improvement` records reusable learnings, errors, feature requests, and promotes recurring lessons into project rules.
-- `ci-cd-and-automation` and `code-review-and-quality` describe automated gates and review axes as quality enforcement mechanisms.
-
-## User Requirements Captured
-
-- GSE must target large, long-running commercial projects first, while degrading for small projects.
-- GSE must be agent-agnostic across Codex, Claude Code, Hermes, WorkBuddy, and similar tools.
-- GSE must support goal maps, specs, evidence, roles, tool acceleration, learning, release, incident, and quality gates.
-- GSE must have few hard prerequisites; optional tools should enhance, not block.
-- GSE itself must be developed using GSE principles.
-- GSE must not invent unsupported facts; evidence and assumptions must be separated.
-- GSE must proactively benchmark itself and project workflows against mature skills and public practices, then convert gaps into goals, gates, templates, or scripts.
-
-## Design Judgments
-
-- Use GSE as the public name because it is short, avoids AES encryption ambiguity, and captures the core loop.
-- Use `.gse/` as the durable project folder because hidden workflow folders are familiar and avoid polluting product docs.
-- Use task levels so small tasks do not inherit enterprise ceremony.
-- Use markdown fallback for all optional tools so the workflow remains portable.
-- Use benchmark audits as a recurring design mechanism because a purely reactive process lets users discover missing requirements through failures.
-
-## Open Questions
-
-- Whether GSE should later publish official adapters for specific hosts, such as Codex Desktop or Claude Code.
-- Whether GSE should include a telemetry dashboard by default or only recommend skill-usage as an optional enhancement.
-- Whether project initialization should update `AGENTS.md` automatically or require explicit approval.
-- How often benchmark audits should run by default: every major project phase, every N slices, or only on explicit request.
+# GSE Design Basis
+
+This file separates verified sources from design judgment.
+
+## Verified Local Sources
+
+- `skill-creator` requires a concise `SKILL.md`, optional `references/`, `scripts/`, and `assets/`, with progressive disclosure and validation.
+- `agentic-engineering` defines eval-first execution, agent-sized decomposition, model routing, and review focus for AI-generated code.
+- `subagent-driven-development` defines fresh subagents per task, explicit roles, spec review, code quality review, and never faking delegation.
+- `comet` combines OpenSpec and Superpowers through open, design, build, verify, archive phases, with hotfix/tweak presets and state files.
+- `openspec-propose` creates proposal, design, specs, and tasks as change artifacts.
+- `self-improvement` records reusable learnings, errors, feature requests, and promotes recurring lessons into project rules.
+- `ci-cd-and-automation` and `code-review-and-quality` describe automated gates and review axes as quality enforcement mechanisms.
+
+## User Requirements Captured
+
+- GSE must target large, long-running commercial projects first, while degrading for small projects.
+- GSE must be agent-agnostic across Codex, Claude Code, Hermes, WorkBuddy, and similar tools.
+- GSE must support goal maps, specs, evidence, roles, tool acceleration, learning, release, incident, and quality gates.
+- GSE must have few hard prerequisites; optional tools should enhance, not block.
+- GSE itself must be developed using GSE principles.
+- GSE must not invent unsupported facts; evidence and assumptions must be separated.
+- GSE must proactively benchmark itself and project workflows against mature skills and public practices, then convert gaps into goals, gates, templates, or scripts.
+
+## Design Judgments
+
+- Use GSE as the public name because it is short, avoids AES encryption ambiguity, and captures the core loop.
+- Use `.gse/` as the durable project folder because hidden workflow folders are familiar and avoid polluting product docs.
+- Use task levels so small tasks do not inherit enterprise ceremony.
+- Use markdown fallback for all optional tools so the workflow remains portable.
+- Use benchmark audits as a recurring design mechanism because a purely reactive process lets users discover missing requirements through failures.
+
+## Open Questions
+
+- Whether GSE should later publish official adapters for specific hosts, such as Codex Desktop or Claude Code.
+- Whether GSE should include a telemetry dashboard by default or only recommend skill-usage as an optional enhancement.
+- Whether project initialization should update `AGENTS.md` automatically or require explicit approval.
+- How often benchmark audits should run by default: every major project phase, every N slices, or only on explicit request.

package/references/domain-model.md

@@ -1,129 +1,129 @@
-# Domain Model
-
-Use this when GSE needs to consume or update a project's domain language, glossary, context files, or ADRs.
-
-## Purpose
-
-Long-running agent work fails when project language drifts. GSE keeps a small domain model layer so future agents can use the project's own words instead of rediscovering or renaming concepts every session.
-
-## Source Files
-
-Read these in order when relevant:
-
-1. `.gse/project-profile.md` for the project identity and known docs.
-2. `CONTEXT.md` for a single-context project glossary.
-3. `CONTEXT-MAP.md` for monorepos or multi-domain projects.
-4. `docs/adr/` or context-specific ADR folders for decisions.
-5. Product specs only after glossary/ADR context is understood.
-
-Do not read all context files in a large monorepo. Use `CONTEXT-MAP.md` or project-profile evidence to pick the relevant context.
-
-## File Roles
-
-| File | Purpose | Should Not Contain |
-|---|---|---|
-| `.gse/project-profile.md` | Short project identity, commands, tools, gates, and doc map | Full glossary, implementation specs, large logs |
-| `CONTEXT.md` | Domain glossary and ubiquitous language | Implementation details, task lists, transient notes |
-| `CONTEXT-MAP.md` | Map from subsystem/domain to its context and ADR files | Detailed definitions that belong in each context |
-| `docs/adr/*.md` | Durable architectural or product decisions | Ordinary implementation notes or temporary preferences |
-| `.gse/changes/*` | Current change outcome, scope, acceptance, evidence | Canonical domain definitions |
-
-## Single-Context Project
-
-Use one root `CONTEXT.md` when the project has one dominant domain language.
-
-```text
-project/
-  CONTEXT.md
-  docs/adr/
-  .gse/project-profile.md
-```
-
-`CONTEXT.md` should define terms like:
-
-- Canonical term.
-- Meaning in this project.
-- Terms not to use.
-- Important relationships to other terms.
-- A short example scenario when it prevents ambiguity.
-
-## Multi-Context Project
-
-Use `CONTEXT-MAP.md` when one glossary would mix unrelated domains.
-
-```text
-project/
-  CONTEXT-MAP.md
-  apps/admin/CONTEXT.md
-  services/billing/CONTEXT.md
-  services/billing/docs/adr/
-  docs/adr/
-```
-
-`CONTEXT-MAP.md` should map:
-
-- Context name.
-- Path to context file.
-- Related code paths.
-- Related ADR path.
-- Owner or review expectation when known.
-
-## When To Update The Domain Model
-
-Update domain files only when the change is durable:
-
-- A term is ambiguous, overloaded, or repeatedly explained.
-- The user resolves a naming conflict.
-- Code and user language disagree about a domain concept.
-- A new durable product concept is introduced.
-- A future agent would likely make a wrong assumption without the note.
-
-Do not update domain files for:
-
-- Temporary implementation details.
-- One-off task notes.
-- Test fixtures that are not domain examples.
-- Preferences that belong in project profile or quality gates.
-
-## ADR Boundary
-
-Create or suggest an ADR only when all are true:
-
-1. Hard to reverse: changing later has meaningful cost.
-2. Surprising without context: future agents or maintainers would ask why.
-3. Real trade-off: there were plausible alternatives.
-
-If any condition is missing, record the fact in the change evidence or project profile instead of creating an ADR.
-
-## Conflict Handling
-
-If project language conflicts:
-
-1. Quote the conflicting sources by path.
-2. Do not silently choose one.
-3. Ask or propose the smallest resolution.
-4. Record the resolved canonical term in the right context file.
-5. If the resolution is hard to reverse and surprising, create or propose an ADR.
-
-## GSE Integration
-
-- `project-profile.md` points agents to the relevant context and ADR files.
-- `spec-workflow.md` should use canonical domain terms from context files.
-- `quality-gates.md` can require domain-language checks for high-risk changes.
-- `evidence-taxonomy.md` still decides whether the domain update is result, verified, or accepted.
-
-## Evidence Examples
-
-Result:
-
-- Added a new glossary entry to `CONTEXT.md`.
-
-Verified:
-
-- Checked the changed spec and code references use the canonical term.
-- Confirmed no conflicting term remains in touched files.
-
-Accepted:
-
-- User, domain owner, reviewer, or policy accepts the new canonical term.
-
+# Domain Model
+
+Use this when GSE needs to consume or update a project's domain language, glossary, context files, or ADRs.
+
+## Purpose
+
+Long-running agent work fails when project language drifts. GSE keeps a small domain model layer so future agents can use the project's own words instead of rediscovering or renaming concepts every session.
+
+## Source Files
+
+Read these in order when relevant:
+
+1. `.gse/project-profile.md` for the project identity and known docs.
+2. `CONTEXT.md` for a single-context project glossary.
+3. `CONTEXT-MAP.md` for monorepos or multi-domain projects.
+4. `docs/adr/` or context-specific ADR folders for decisions.
+5. Product specs only after glossary/ADR context is understood.
+
+Do not read all context files in a large monorepo. Use `CONTEXT-MAP.md` or project-profile evidence to pick the relevant context.
+
+## File Roles
+
+| File | Purpose | Should Not Contain |
+|---|---|---|
+| `.gse/project-profile.md` | Short project identity, commands, tools, gates, and doc map | Full glossary, implementation specs, large logs |
+| `CONTEXT.md` | Domain glossary and ubiquitous language | Implementation details, task lists, transient notes |
+| `CONTEXT-MAP.md` | Map from subsystem/domain to its context and ADR files | Detailed definitions that belong in each context |
+| `docs/adr/*.md` | Durable architectural or product decisions | Ordinary implementation notes or temporary preferences |
+| `.gse/changes/*` | Current change outcome, scope, acceptance, evidence | Canonical domain definitions |
+
+## Single-Context Project
+
+Use one root `CONTEXT.md` when the project has one dominant domain language.
+
+```text
+project/
+  CONTEXT.md
+  docs/adr/
+  .gse/project-profile.md
+```
+
+`CONTEXT.md` should define terms like:
+
+- Canonical term.
+- Meaning in this project.
+- Terms not to use.
+- Important relationships to other terms.
+- A short example scenario when it prevents ambiguity.
+
+## Multi-Context Project
+
+Use `CONTEXT-MAP.md` when one glossary would mix unrelated domains.
+
+```text
+project/
+  CONTEXT-MAP.md
+  apps/admin/CONTEXT.md
+  services/billing/CONTEXT.md
+  services/billing/docs/adr/
+  docs/adr/
+```
+
+`CONTEXT-MAP.md` should map:
+
+- Context name.
+- Path to context file.
+- Related code paths.
+- Related ADR path.
+- Owner or review expectation when known.
+
+## When To Update The Domain Model
+
+Update domain files only when the change is durable:
+
+- A term is ambiguous, overloaded, or repeatedly explained.
+- The user resolves a naming conflict.
+- Code and user language disagree about a domain concept.
+- A new durable product concept is introduced.
+- A future agent would likely make a wrong assumption without the note.
+
+Do not update domain files for:
+
+- Temporary implementation details.
+- One-off task notes.
+- Test fixtures that are not domain examples.
+- Preferences that belong in project profile or quality gates.
+
+## ADR Boundary
+
+Create or suggest an ADR only when all are true:
+
+1. Hard to reverse: changing later has meaningful cost.
+2. Surprising without context: future agents or maintainers would ask why.
+3. Real trade-off: there were plausible alternatives.
+
+If any condition is missing, record the fact in the change evidence or project profile instead of creating an ADR.
+
+## Conflict Handling
+
+If project language conflicts:
+
+1. Quote the conflicting sources by path.
+2. Do not silently choose one.
+3. Ask or propose the smallest resolution.
+4. Record the resolved canonical term in the right context file.
+5. If the resolution is hard to reverse and surprising, create or propose an ADR.
+
+## GSE Integration
+
+- `project-profile.md` points agents to the relevant context and ADR files.
+- `spec-workflow.md` should use canonical domain terms from context files.
+- `quality-gates.md` can require domain-language checks for high-risk changes.
+- `evidence-taxonomy.md` still decides whether the domain update is result, verified, or accepted.
+
+## Evidence Examples
+
+Result:
+
+- Added a new glossary entry to `CONTEXT.md`.
+
+Verified:
+
+- Checked the changed spec and code references use the canonical term.
+- Confirmed no conflicting term remains in touched files.
+
+Accepted:
+
+- User, domain owner, reviewer, or policy accepts the new canonical term.
+

package/references/domain-quality-gates.md

@@ -1,75 +1,75 @@
-# Domain Quality Gates
-
-Use this when a task has domain risk beyond basic file or script correctness. Pick only the gates that match the changed behavior and project risk.
-
-This reference is risk-based. Lite work should not inherit every gate by default. Commercial, user-visible, data-bearing, security-sensitive, release, or long-running work should receive stronger gates.
-
-## Selection Rule
-
-Choose gates by asking:
-
-1. What could fail for users, data, operators, maintainers, or future agents?
-2. Which project files, tests, commands, docs, or runtime checks can prove the risk is controlled?
-3. Is the evidence `result`, `verified`, or `accepted` according to `references/evidence-taxonomy.md`?
-4. Is a tool merely documented, or was it actually run in this project/session?
-
-Do not claim scan, benchmark, browser, accessibility, security, or resilience results unless the relevant command or inspection was actually executed.
-
-## Scale Guidance
-
-| Level | Default domain gate weight |
-|---|---|
-| Lite | Use only the directly relevant gate and one focused evidence point. |
-| Standard | Use relevant domain gates plus regression or smoke evidence. |
-| Enterprise | Use a risk matrix, review axis, release/recovery path, and project-specific evidence. |
-
-Upgrade the gate weight when a change touches public APIs, user data, auth, payments, model/provider routing, migrations, release, cross-module state, worker orchestration, browser automation, or main-path UX.
-
-## Gate Matrix
-
-| Domain | Trigger | Minimum evidence | Escalate when |
-|---|---|---|---|
-| Security/privacy | Secrets, auth, permissions, user data, provider payloads, MCP/tools, browser traces, logs | Secret scan or file inspection, permission boundary review, no raw secrets/provider payloads in committed or user-visible output | Data exposure, auth bypass, destructive tools, public release, external services |
-| Performance/cost | Latency, heavy context loading, loops, model/tool routing, worker queues, browser automation, large files | Focused timing, complexity review, query/count check, or explicit cost/latency rationale | Main path, repeated tasks, expensive models, user-visible slowness, scale-sensitive code |
-| Accessibility | UI, keyboard flow, forms, visual states, text contrast, semantic structure | Browser smoke, component inspection, keyboard/focus check, or accessibility tool result when available | User-facing UI, forms, navigation, mobile/responsive layout, public release |
-| Resilience/recovery | Retry, cancellation, timeout, idempotency, duplicate prevention, state recovery, fallback | Failure-path inspection, focused test/smoke for retry/cancel/error state, recovery record when interrupted | Worker/runtime changes, long tasks, external APIs, stateful workflows, release rollback |
-| UI/browser | Visual behavior, loading/empty/error/success states, routing, layout, streaming, browser automation | Browser smoke, screenshot/visual inspection, component test, or DOM/state inspection | Main user flow, responsive UI, visual regression risk, rich interaction |
-| API/state | API contracts, persistence, state machines, cache, sessions, concurrency, idempotency | Focused API smoke, state transition test, schema/config inspection, replay/idempotency check | Public API, cross-session state, migrations, concurrent writes, data retention |
-| Data/migration | Schema, storage, generated artifacts, imports/exports, backward compatibility | Migration/rollback notes, fixture data smoke, backup/restore plan, compatibility check | Production data, irreversible transform, downgrade uncertainty, multi-version support |
-| Model/tool routing | Model provider, tool call, MCP, browser, subagent, permission, cost route | Tool status marked documented/verified/unknown/unavailable; provider/model behavior verified only after execution | New provider, fallback, sensitive data, expensive model, hidden tool traces |
-| Release/operations | Install, update, release notes, rollback, incident, observability | `references/release.md`, `references/recovery.md`, release readiness audit, known risks | Public handoff, package update, runtime compatibility, incident hotfix |
-
-## Evidence Mapping
-
-Use the narrowest evidence that would fail if the changed behavior were broken.
-
-- File inspection can verify docs, templates, source-of-truth boundaries, and secret absence in touched files.
-- Focused tests can verify code behavior, state transitions, error paths, and regressions.
-- API smokes can verify contracts, persistence, and session behavior.
-- Browser smokes can verify UI, accessibility basics, streaming, loading/error states, and layout-sensitive flows.
-- Architecture/review scans can verify coupling, ownership, release risk, and residual risk when runtime execution is not available.
-
-If evidence is unavailable, record `unknown` or `not ready`; do not promote to `verified`.
-
-## Review Routing
-
-- Use `references/review.md` for spec compliance, code quality, architecture drift, security/privacy, regression, and evidence review axes.
-- Use `references/architecture-health.md` when the task touches structural boundaries, source-of-truth drift, dependency/security risk, performance/resilience, migration, or release impact.
-- Use `references/release.md` and `references/recovery.md` when domain risk affects release, rollback, migration, incident response, or future-agent continuation.
-- Use `.gse/project-profile.md` for project-specific commands, owners, threat model, performance budget, browser matrix, release gates, and compliance requirements.
-
-## Output Format
-
-Record domain gates compactly:
-
-```text
-Domain gates selected:
-Why selected:
-Evidence run:
-Evidence status: result | verified | accepted | not ready
-Unverified tools:
-Residual risk:
-Next action:
-```
-
-For skipped gates, say why they are not applicable or what evidence would be needed later.
+# Domain Quality Gates
+
+Use this when a task has domain risk beyond basic file or script correctness. Pick only the gates that match the changed behavior and project risk.
+
+This reference is risk-based. Lite work should not inherit every gate by default. Commercial, user-visible, data-bearing, security-sensitive, release, or long-running work should receive stronger gates.
+
+## Selection Rule
+
+Choose gates by asking:
+
+1. What could fail for users, data, operators, maintainers, or future agents?
+2. Which project files, tests, commands, docs, or runtime checks can prove the risk is controlled?
+3. Is the evidence `result`, `verified`, or `accepted` according to `references/evidence-taxonomy.md`?
+4. Is a tool merely documented, or was it actually run in this project/session?
+
+Do not claim scan, benchmark, browser, accessibility, security, or resilience results unless the relevant command or inspection was actually executed.
+
+## Scale Guidance
+
+| Level | Default domain gate weight |
+|---|---|
+| Lite | Use only the directly relevant gate and one focused evidence point. |
+| Standard | Use relevant domain gates plus regression or smoke evidence. |
+| Enterprise | Use a risk matrix, review axis, release/recovery path, and project-specific evidence. |
+
+Upgrade the gate weight when a change touches public APIs, user data, auth, payments, model/provider routing, migrations, release, cross-module state, worker orchestration, browser automation, or main-path UX.
+
+## Gate Matrix
+
+| Domain | Trigger | Minimum evidence | Escalate when |
+|---|---|---|---|
+| Security/privacy | Secrets, auth, permissions, user data, provider payloads, MCP/tools, browser traces, logs | Secret scan or file inspection, permission boundary review, no raw secrets/provider payloads in committed or user-visible output | Data exposure, auth bypass, destructive tools, public release, external services |
+| Performance/cost | Latency, heavy context loading, loops, model/tool routing, worker queues, browser automation, large files | Focused timing, complexity review, query/count check, or explicit cost/latency rationale | Main path, repeated tasks, expensive models, user-visible slowness, scale-sensitive code |
+| Accessibility | UI, keyboard flow, forms, visual states, text contrast, semantic structure | Browser smoke, component inspection, keyboard/focus check, or accessibility tool result when available | User-facing UI, forms, navigation, mobile/responsive layout, public release |
+| Resilience/recovery | Retry, cancellation, timeout, idempotency, duplicate prevention, state recovery, fallback | Failure-path inspection, focused test/smoke for retry/cancel/error state, recovery record when interrupted | Worker/runtime changes, long tasks, external APIs, stateful workflows, release rollback |
+| UI/browser | Visual behavior, loading/empty/error/success states, routing, layout, streaming, browser automation | Browser smoke, screenshot/visual inspection, component test, or DOM/state inspection | Main user flow, responsive UI, visual regression risk, rich interaction |
+| API/state | API contracts, persistence, state machines, cache, sessions, concurrency, idempotency | Focused API smoke, state transition test, schema/config inspection, replay/idempotency check | Public API, cross-session state, migrations, concurrent writes, data retention |
+| Data/migration | Schema, storage, generated artifacts, imports/exports, backward compatibility | Migration/rollback notes, fixture data smoke, backup/restore plan, compatibility check | Production data, irreversible transform, downgrade uncertainty, multi-version support |
+| Model/tool routing | Model provider, tool call, MCP, browser, subagent, permission, cost route | Tool status marked documented/verified/unknown/unavailable; provider/model behavior verified only after execution | New provider, fallback, sensitive data, expensive model, hidden tool traces |
+| Release/operations | Install, update, release notes, rollback, incident, observability | `references/release.md`, `references/recovery.md`, release readiness audit, known risks | Public handoff, package update, runtime compatibility, incident hotfix |
+
+## Evidence Mapping
+
+Use the narrowest evidence that would fail if the changed behavior were broken.
+
+- File inspection can verify docs, templates, source-of-truth boundaries, and secret absence in touched files.
+- Focused tests can verify code behavior, state transitions, error paths, and regressions.
+- API smokes can verify contracts, persistence, and session behavior.
+- Browser smokes can verify UI, accessibility basics, streaming, loading/error states, and layout-sensitive flows.
+- Architecture/review scans can verify coupling, ownership, release risk, and residual risk when runtime execution is not available.
+
+If evidence is unavailable, record `unknown` or `not ready`; do not promote to `verified`.
+
+## Review Routing
+
+- Use `references/review.md` for spec compliance, code quality, architecture drift, security/privacy, regression, and evidence review axes.
+- Use `references/architecture-health.md` when the task touches structural boundaries, source-of-truth drift, dependency/security risk, performance/resilience, migration, or release impact.
+- Use `references/release.md` and `references/recovery.md` when domain risk affects release, rollback, migration, incident response, or future-agent continuation.
+- Use `.gse/project-profile.md` for project-specific commands, owners, threat model, performance budget, browser matrix, release gates, and compliance requirements.
+
+## Output Format
+
+Record domain gates compactly:
+
+```text
+Domain gates selected:
+Why selected:
+Evidence run:
+Evidence status: result | verified | accepted | not ready
+Unverified tools:
+Residual risk:
+Next action:
+```
+
+For skipped gates, say why they are not applicable or what evidence would be needed later.