@t275005746/gse 0.1.0

package/references/recovery.md

@@ -0,0 +1,176 @@
+# Recovery And Handoff
+
+Use this when work is interrupted, verification fails, a tool or runtime is unavailable, partial edits exist, release rollback may be needed, or a future agent must continue without relying on hidden context.
+
+Recovery and handoff are part of the evidence loop. The goal is to make the current state understandable, resumable, and reversible.
+
+## Trigger Conditions
+
+Run this protocol when any of these are true:
+
+- A session is interrupted, refreshed, compacted, or handed to another agent or host.
+- A command, tool, MCP server, browser path, model route, subagent dispatch, or verification gate fails unexpectedly.
+- The worktree has partial edits, generated artifacts, dirty files, or uncertain ownership.
+- A release, migration, rollback, hotfix, incident, or compatibility issue is involved.
+- The current agent cannot finish safely within the active slice but has useful evidence or decisions to preserve.
+- The user asks to continue from another session, branch, host, or agent.
+
+Do not create a heavy handoff for a tiny completed edit that already has direct evidence and no residual risk.
+
+## Failure Classification
+
+Classify the situation before deciding the next step.
+
+| Class | Meaning | Default action |
+|---|---|---|
+| recoverable failure | A command, test, tool, or assumption failed, but the path is still clear | Record failure, fix smallest cause, rerun focused evidence |
+| blocked work | Progress needs user input, missing credentials, unavailable external service, or unavailable required tool | Record blocker, preserve state, ask for the smallest required input |
+| rollback required | Current edits or release state are unsafe, misleading, or harmful | Stop new work, identify owned edits, follow project rollback policy |
+| handoff required | Another session, agent, host, branch, or future run must continue | Record goal, current state, changed files, evidence, risks, and next action |
+| incident recovery | Main path, data, security, privacy, release, or user-visible behavior is broken | Stabilize first, preserve evidence, route through release/incident gates |
+
+Never hide a failed check by reducing acceptance. Either fix it, mark it as residual risk, or move the slice to not ready.
+
+## Resume Or Rollback Decision
+
+Choose one path and record why:
+
+- Resume: use when edits are scoped, evidence is trustworthy, and the next verification step is clear.
+- Repair: use when a known broken command, test, route, or doc can be fixed inside the current slice.
+- Roll back owned edits: use when the current changes are unsafe, contradict scope, or cannot be verified.
+- Preserve and hand off: use when meaningful progress exists but completion requires another session, role, host, or external condition.
+- Stop and ask: use when user input is required and any assumption would risk data, security, release, or product direction.
+
+Do not revert user work or unrelated dirty files. Use references/file-ownership.md before rollback or cleanup.
+
+## Failed Verification Path
+
+When verification fails, do not reduce the acceptance bar to make the slice look complete.
+
+Use this sequence:
+
+1. Preserve the failed command, status, and narrow failure reason.
+2. Decide whether the failure invalidates the result, only blocks verification, or exposes unrelated existing risk.
+3. Fix the smallest reusable artifact when the cause is inside the slice.
+4. Re-run the same focused verification before adding new scope.
+5. If the failure cannot be fixed in the slice, mark readiness `not ready` or `result`, record the blocker, and set the next action.
+
+If the failure concerns release, migration, rollback, public behavior, security/privacy, or data safety, route through `references/release.md` before claiming readiness.
+
+## Release Recovery Path
+
+Use this when release validation, install/update handoff, migration, rollback, compatibility, or incident gates fail.
+
+Minimum release recovery record:
+
+```text
+Release scope:
+Failed gate:
+Release level:
+Readiness after failure: not ready | result | verified | accepted
+What changed:
+What remains safe:
+Rollback or resume decision:
+Files or artifacts to revert:
+Verification to rerun:
+Owner or decision needed:
+Next action:
+```
+
+Rules:
+
+- Do not call a release accepted while a required release gate is failing.
+- Prefer file-level revert for low-risk docs/scripts when ownership is clear.
+- For generated scaffolds, host adapters, state, schema, runtime config, or compatibility-impacting changes, document downstream regeneration or migration impact.
+- If rollback touches user or unrelated files, stop and use `references/file-ownership.md` before changing them.
+
+## Incident Follow-Up Path
+
+Use `assets/templates/incident-review.md` when the recovery involves user-visible breakage, data loss/corruption risk, security/privacy risk, release blocker, repeated failed verification, or a broken main path.
+
+Incident follow-up must separate:
+
+- Impact and affected users/systems.
+- Timeline and detection signal.
+- Root cause and contributing factors.
+- Immediate stabilization.
+- Verification that proves stabilization.
+- Long-term prevention tasks.
+- Evidence links and owners.
+
+Do not turn every failed command into an incident. Use incident review only when the failure has product, release, safety, or repeated-process significance.
+
+## Future-Agent Continuation Packet
+
+When work must continue elsewhere, provide a compact packet that a future agent can run without hidden memory:
+
+```text
+Goal or spec:
+Active slice:
+Current evidence status:
+Changed files:
+Files intentionally untouched:
+Commands already run:
+Failed or unavailable tools:
+Release/recovery decision:
+Rollback notes:
+Next verification command:
+Next action:
+```
+
+If the handoff is meant to prove fresh-session acceptance, use `references/forward-test.md` and record `accepted by: fresh-session` only after a separate session actually follows the packet.
+
+## Minimum Recovery Record
+
+Use this compact format in evidence logs, handoffs, or final status:
+
+```text
+Recovery class:
+Current objective:
+Current state:
+Changed files:
+Commands run:
+Failed or unavailable tools:
+Evidence that still holds:
+Evidence that is missing or weak:
+Rollback or resume decision:
+Risks:
+Next action:
+```
+
+Keep command output short. Link to logs or evidence files instead of pasting noisy output.
+
+## Handoff Requirements
+
+A future-agent handoff must include:
+
+- The active goal or spec and the current slice outcome.
+- Files changed and files intentionally left untouched.
+- Commands/tests/smokes already run and their result status.
+- Known blockers, assumptions, unavailable tools, and residual risk.
+- The next concrete action, not a vague instruction to investigate everything.
+- Any project-specific rules from `.gse/project-profile.md`, AGENTS.md, or host adapter notes that affected the work.
+- Whether the work is result, verified, accepted, blocked, rollback required, or not ready according to references/evidence-taxonomy.md.
+
+If real subagent tools are unavailable, say so. A sequential-role note or handoff is not real delegation.
+
+## Verification After Recovery
+
+After resuming from recovery or handoff:
+
+- Re-read the controlling goal, current slice, and project rules before editing.
+- Inspect current files instead of trusting the handoff blindly.
+- Re-run the smallest focused evidence that proves the recovered path still works.
+- Reclassify readiness with references/evidence-taxonomy.md.
+- Update the evidence log with what changed since the handoff.
+
+If evidence changed or contradicted the handoff, prefer current-state evidence.
+
+## Integration
+
+- Use references/file-ownership.md before reverting, moving, deleting, or cleaning files.
+- Use references/release.md when recovery affects release, rollback, migration, changelog/release notes, or release acceptance.
+- Use references/quality-gates.md when failed verification, cancellation, retry, or recovery behavior affects completion.
+- Use references/review.md when recovery changes code, shared workflow rules, release paths, security/privacy behavior, or user-visible product behavior.
+- Use references/forward-test.md when recovery or handoff rules become reusable GSE behavior that future agents must follow.
+- Use references/learning-system.md only for reusable lessons; do not log noisy transient failures.

package/references/release-trust.md

@@ -0,0 +1,43 @@
+# Release Trust
+
+Use this when preparing GSE for public, shared, or marketplace-style distribution.
+
+GSE signing mechanics prove that a package matches a signed manifest. They do not prove maintainer identity, public key custody, account security, or marketplace trust. Treat those as release governance.
+
+## Required Release Trust Record
+
+For every public release, record:
+
+- Release label and package digest.
+- Public key fingerprint.
+- Maintainer or release owner.
+- Signing machine or signing environment.
+- Key custody location.
+- Rotation policy.
+- Revocation path if a key is compromised.
+- Verification command used by a fresh install.
+- Accepted by owner or release authority.
+
+Use `assets/templates/release-trust-record.md`.
+
+## Key Custody Rules
+
+Key custody is a release owner responsibility.
+
+- Do not commit private keys.
+- Do not package private keys.
+- Do not generate production keys inside a temporary audit folder.
+- Store production private keys in a host secret store, hardware-backed key store, or explicitly approved private release environment.
+- Publish public keys and fingerprints with release notes.
+- Rotate keys when custody changes, maintainer access changes, or compromise is suspected.
+- Keep an owner-approved revocation note for retired keys.
+
+## Verification Rules
+
+A release can claim:
+
+- `signed`: a package signature exists.
+- `verified`: `verify-gse-package.mjs` passes against the published public key.
+- `trusted`: signed and verified, with an owner-accepted release trust record.
+
+Do not claim `trusted` from signing alone.

package/references/release.md

@@ -0,0 +1,126 @@
+# Release Workflow
+
+Use this when a GSE slice affects shipping, installation, upgrade, runtime compatibility, user-visible behavior, migrations, rollback, changelog policy, or long-running project readiness.
+
+Release workflow is a gate, not a deployment tool. It defines what must be known before claiming a release is ready.
+
+## Trigger Conditions
+
+Run this workflow when any of these are true:
+
+- A change is intended for a versioned release, public handoff, package update, installer update, or user-facing delivery.
+- A change affects install, bootstrap, update, compatibility, migration, rollback, data retention, or runtime configuration.
+- A change modifies product identity, permissions, model/provider routing, worker behavior, state persistence, evidence gates, or generated project scaffold files.
+- A bug fix touches a main path where regression risk matters.
+- Architecture health scan reports migration, release, rollback, dependency, security, or ownership risk.
+- The project requires changelog, release notes, approvals, or deployment evidence.
+
+For tiny internal edits with no release surface, record why release workflow is not applicable.
+
+## Release Levels
+
+Pick the smallest release level that matches the blast radius.
+
+| Level | Use when | Minimum gate |
+|---|---|---|
+| Patch | Bug fix, doc correction, template wording, low-risk scaffold update | Focused verification, known risk, release note if user-visible |
+| Minor | New capability, new template, new script behavior, new adapter route, non-breaking workflow change | Focused verification, backward compatibility check, rollback or revert path, release notes |
+| Major | Breaking workflow, migration, removed behavior, changed source of truth, broad architecture change | Migration plan, rollback plan, compatibility notes, architecture health scan, release acceptance evidence |
+| Incident hotfix | Urgent fix for broken main path, data risk, security/privacy issue, release blocker | Minimal safe fix, reproduction or failure evidence, focused verification, incident follow-up |
+
+## Minimum Release Checklist
+
+Before calling a release ready, confirm:
+
+- Outcome and scope match the accepted goal or spec.
+- Version or release label is known, or the project explicitly does not use version labels.
+- Changelog or release notes explain user-visible changes, breaking changes, migration notes, and known risks.
+- Focused verification proves the changed behavior, not only file existence.
+- Compatibility impact is checked against supported hosts, runtimes, package managers, project modes, and important configuration paths.
+- Migration and rollback expectations are documented for any state, schema, config, scaffold, or runtime change.
+- Security, privacy, permissions, secrets, and raw tool/provider traces are reviewed when relevant.
+- Observability, error diagnosis, or incident path is adequate for risky changes.
+- Evidence status is classified with references/evidence-taxonomy.md: result, verified, or accepted.
+- Follow-up slices are recorded instead of hidden in final prose.
+
+## Migration And Rollback
+
+Capture migration and rollback at the same level of detail as the risk.
+
+For low-risk changes:
+
+- State whether revert is enough.
+- Name the files or artifacts that would be reverted.
+
+For stateful or compatibility-impacting changes:
+
+- Define old state, new state, and compatibility window.
+- Define data backup, restore, or fallback behavior.
+- Define how to detect failed migration or partial rollout.
+- Define whether downgrade is supported.
+
+For release-blocking uncertainty, do not claim accepted. Record a decision needed or follow-up slice.
+
+## Changelog And Release Notes Policy
+
+Use the project convention first. If none exists, keep release notes short and structured:
+
+```text
+Release label:
+Date:
+Type: patch | minor | major | incident hotfix
+Highlights:
+Changed:
+Fixed:
+Migration or rollback:
+Known risks:
+Verification:
+Follow-up slices:
+```
+
+Rules:
+
+- Mention user-visible behavior separately from internal implementation.
+- Mark breaking changes clearly.
+- Do not include secrets, raw provider payloads, private reasoning, or noisy command logs.
+- Link to evidence files or CI/test results instead of pasting long output.
+- If the release is internal-only, say so and explain the affected operators or future agents.
+
+## Release Evidence Record
+
+Use `assets/templates/update-release-acceptance-record.md` when a project needs to preserve local decisions, changed files, rollback notes, owner gate, accepted-by status, and residual risk in one compact record.
+
+For quick release notes, use this concise format in evidence logs or release notes:
+
+```text
+Release scope:
+Release level:
+Readiness: not ready | result | verified | accepted
+Verification evidence:
+Compatibility evidence:
+Migration or rollback:
+Known risks:
+Decisions needed:
+Follow-up slices:
+```
+
+Readiness meanings:
+
+- not ready: required release evidence is missing or contradicted.
+- result: release artifacts or notes exist, but behavior is not verified.
+- verified: focused checks prove release-relevant behavior in the current environment.
+- accepted: the required owner, CI, smoke, or production-like evidence for this release level has passed.
+
+Do not mark `accepted` only because local validation passed. Use `accepted` only when the required owner, release policy, CI gate, smoke gate, archive gate, or explicitly named acceptance policy accepts the verified result.
+
+## Integration
+
+- Use references/quality-gates.md for the base release gate list.
+- Use references/public-release.md before public GitHub, marketplace, catalog, registry, or external package handoff.
+- Use references/architecture-health.md when migration, rollback, dependency, security, performance, resilience, compatibility, or source-of-truth risk exists.
+- Use references/review.md for spec compliance, code quality, security/privacy, regression, and evidence review before release.
+- Use references/project-profile.md for project-specific release commands, versioning, deployment, rollback, and approval rules.
+- Use references/evidence-taxonomy.md to avoid overstating readiness.
+- Use references/recovery.md when release work is interrupted, rollback is possible, verification fails, or future-agent continuation is needed.
+- Use references/forward-test.md for non-trivial GSE release, scaffold, adapter, recovery, or packaging changes.
+- Use `assets/templates/update-release-acceptance-record.md` for project-local update and release acceptance records.

package/references/review.md

@@ -0,0 +1,141 @@
+# Review Protocol
+
+Use this when GSE work needs a review beyond simple local verification: code changes, workflow rules, scaffolds, agent roles, adapters, release paths, security-sensitive behavior, or user-visible product behavior.
+
+## Core Rule
+
+Review must answer two separate questions:
+
+1. Spec compliance: did we build the requested thing and only the requested thing?
+2. Code/workflow quality: is the result maintainable, safe, testable, and consistent with the project?
+
+Do not collapse these into a vague "looks good" check.
+
+## When Review Is Required
+
+| Task risk | Review requirement |
+|---|---|
+| Level 1 tiny edit | Optional; self-check against acceptance is enough when evidence is direct |
+| Level 2 normal slice | Required if code, shared config, reusable templates, workflow rules, or user-visible behavior changed |
+| Level 3 large/risky work | Required; separate spec compliance, quality, QA/evidence, and coordinator integration review |
+| Security/privacy/release impact | Required; include security/privacy and rollback/evidence review |
+| Multi-agent or delegated work | Required when roles modify files or produce evidence |
+
+Review is unnecessary for evidence-only status updates, typo-only edits, or transient notes unless they change process meaning.
+
+## Review Axes
+
+### 1. Spec Compliance Review
+
+Checks whether the result matches the defined outcome, scope, non-goals, and acceptance criteria.
+
+Questions:
+
+- Does the change satisfy the requested outcome?
+- Did scope expand silently?
+- Were non-goals respected?
+- Are required files/artifacts present?
+- Is the evidence directly tied to acceptance?
+- Are user-visible names, identities, and permissions correct?
+
+### 2. Code Quality Review
+
+Checks maintainability and implementation quality.
+
+Questions:
+
+- Does the change follow existing project patterns?
+- Is the code or workflow simpler than the problem requires?
+- Are abstractions justified?
+- Are generated files, lockfiles, or unrelated refactors avoided?
+- Are edge cases, errors, retries, cancellation, or recovery handled when relevant?
+
+### 3. Architecture Drift Review
+
+Checks whether the change preserves project boundaries and long-term shape.
+
+Questions:
+
+- Did this introduce a new pattern without need?
+- Does it cross module, package, product, or host boundaries incorrectly?
+- Does it duplicate a source of truth?
+- Does it create coupling that future agents will misunderstand?
+- Should the issue be handled by a `references/architecture-health.md` scan?
+
+### 4. Security And Privacy Review
+
+Checks user data, secrets, permissions, external services, and tool traces.
+
+Questions:
+
+- Are secrets, tokens, raw provider payloads, and hidden reasoning excluded from user-visible output and committed files?
+- Are write-capable tools and destructive commands bounded?
+- Are external inputs treated as untrusted?
+- Are privacy constraints respected for model routing, logs, browser traces, and MCP/tools?
+
+### 5. Regression And Missing-Test Review
+
+Checks whether the verification actually covers the changed behavior.
+
+Questions:
+
+- Would the focused test/smoke fail if the change were broken?
+- Are existing tests or checks enough for this risk?
+- Is a regression test needed for a bug fix?
+- Are UI/API/state/error/cancel/retry paths covered when relevant?
+
+### 6. Evidence Review
+
+Checks whether the final claim is supported.
+
+Questions:
+
+- Is the status result, verified, or accepted according to `references/evidence-taxonomy.md`?
+- Is residual risk recorded?
+- Is a forward test required by `references/forward-test.md`?
+- Are tool statuses documented, verified, unknown, or unavailable without exaggeration?
+
+## Review Output
+
+Use this concise format:
+
+```text
+Review type: spec compliance | code quality | architecture drift | security/privacy | regression/missing-test | evidence
+Verdict: approve | request changes | needs context | not applicable
+Severity: critical | important | suggestion | note
+Findings:
+Evidence checked:
+Required fixes:
+Deferred risks:
+```
+
+For no-issue reviews, say which axes were checked. Do not rubber-stamp with only `LGTM`.
+
+## Severity Rules
+
+- `critical`: security issue, data loss, broken main path, destructive operation, irreversible release risk.
+- `important`: likely bug, missing acceptance evidence, meaningful architecture drift, missing regression coverage.
+- `suggestion`: improvement that is useful but not required for this slice.
+- `note`: context for future work, no action required.
+
+## Multi-Agent Review Order
+
+When using real subagents or sequential role simulation:
+
+1. Builder reports files changed and verification run.
+2. Spec compliance review checks scope and acceptance first.
+3. Code quality review checks maintainability and risks second.
+4. QA/evidence review confirms the verification story.
+5. Coordinator integrates findings and decides final status.
+
+Do not start code-quality approval before unresolved spec compliance issues are addressed.
+
+## Project Integration
+
+- `references/agent-roles.md` defines Reviewer and QA responsibilities.
+- `assets/templates/dispatch-packet.md` records whether spec compliance, code quality, QA/evidence, and coordinator review are required.
+- `references/architecture-health.md` defines structural scan triggers, scope levels, findings, risks, decisions, and follow-up slices.
+- `references/quality-gates.md` decides when review is required by risk.
+- `references/domain-quality-gates.md` selects security/privacy, performance/cost, accessibility, resilience/recovery, UI/browser, API/state, data/migration, model/tool routing, and release/operations gates by domain risk.
+- `references/evidence-taxonomy.md` decides whether a reviewed result is verified or accepted.
+- `.gse/project-profile.md` can add project-specific review standards, owners, or required commands.

package/references/router.md

@@ -0,0 +1,90 @@
+# Router
+
+Use this to choose the GSE path before loading detailed references. The router selects; it does not replace the selected reference files.
+
+## Inputs
+
+Classify the request with these inputs:
+
+- Work target: GSE skill itself, a project adopting GSE, or ordinary project work inside a GSE project.
+- Task level: Lite, Standard, or Enterprise from `task-levels.md`.
+- Change type: setup, feature, bug, refactor, research, UI, release, incident, skill improvement, or tool adapter.
+- Tool availability: verified, documented, unknown, or unavailable from `tool-adapters.md`.
+- Project constraints: `.gse/project-profile.md`, AGENTS/CLAUDE/GEMINI rules, CI, MCP, LSP, browser, release, and security boundaries.
+- Command-style usage: `/gse ...`, `gse: ...`, or equivalent natural-language command from `commands.md`.
+
+## Universal Start
+
+For meaningful work:
+
+1. Read project or skill rules first.
+2. Read `.gse/project-profile.md` when working inside a project.
+3. Read `.gse/gse-design-master-plan.md`, `.gse/goal-map.md`, and `.gse/current-slice.md` when improving GSE itself.
+4. If the request starts with `/gse` or `gse:`, load `references/commands.md` and map the command before selecting the route.
+5. Select one route below.
+6. Load only the reference files required by that route.
+
+## Route Map
+
+| Situation | Route | Required References | Optional Adapters |
+|---|---|---|---|
+| User asks `/gse ...` or `gse: ...` | Command routing | `commands.md`, then the mapped route reference | host-specific slash command adapters |
+| Improve GSE skill itself | GSE self-development | `.gse/gse-development-protocol.md`, `.gse/gse-design-master-plan.md`, `benchmark-audit.md` | `audit-gse.mjs`, `skill-creator`, benchmark repos |
+| Initialize GSE in a project | Project bootstrap | `project-bootstrap.md`, `project-profile.md`, `project-agent-workspace.md` | `init-project.mjs` |
+| Discover project rules/tools | Project profile | `project-profile.md`, `tool-adapters.md` | future `discover-project-profile.mjs`, LSP, MCP, CI |
+| Plan feature or product slice | Spec workflow | `task-levels.md`, `goal-map.md`, `spec-workflow.md`, `quality-gates.md` | OpenSpec, Comet, subagents |
+| Implement bounded slice | Execute workflow | `operating-model.md`, `quality-gates.md`, `tool-adapters.md` | TDD, LSP, browser QA, CI |
+| Debug bug or incident | Recovery workflow | `quality-gates.md`, `learning-system.md`; add recovery reference when available | browser/API smoke, logs, incident review |
+| UI or browser-visible change | UI verification | `quality-gates.md`, `tool-adapters.md`, project profile | Browser, Playwright, screenshots |
+| Multi-agent execution | Role workflow | `agent-roles.md`, `quality-gates.md` | subagent tools, worktrees, file ownership reference when available |
+| Release or migration | Release workflow | `quality-gates.md`; add release reference when available | CI, deployment, smoke, rollback |
+| Add or evaluate tool adapter | Adapter workflow | `tool-adapters.md`, `project-profile.md`, `benchmark-audit.md` for GSE changes | MCP, LSP, browser, model routing |
+| Record reusable lesson | Learning workflow | `learning-system.md` | self-improvement |
+
+## Level Rules
+
+Lite:
+
+- Use when the task is small, local, low-risk, and independently verifiable.
+- Keep artifacts minimal: outcome, scope, acceptance, evidence, next action.
+- Do not create a change folder unless it prevents confusion.
+
+Standard:
+
+- Use for user-visible behavior, API/state changes, multi-file edits, project setup, or GSE reference/script changes.
+- Bind to goal map or current slice.
+- Record evidence in `.gse/evidence/` or the project evidence log.
+
+Enterprise:
+
+- Use for cross-module architecture, release, migration, security, multi-agent execution, compliance, or long-running productization.
+- Require explicit gates for risk, rollback, ownership, verification, and learning.
+
+## Tool Routing Rules
+
+- Use `rg`/`rg --files` first for code and file discovery.
+- Use LSP/index when verified or documented for the project.
+- Use browser/Playwright for user-visible UI behavior.
+- Use API smoke or focused tests for API/state behavior.
+- Use OpenSpec or Comet when the project has them and the change benefits from formal lifecycle artifacts.
+- Use subagents only when real dispatch tools exist; otherwise execute roles sequentially and say so.
+- Use markdown fallback when optional tools are unavailable.
+
+## GSE Self-Development Route
+
+When changing GSE itself:
+
+1. Read `.gse/gse-design-master-plan.md`, `.gse/goal-map.md`, and `.gse/current-slice.md`.
+2. Run or consult `scripts/audit-gse.mjs` to see current structural gaps.
+3. If the change is non-trivial, update or create a benchmark audit.
+4. Prefer scripts/templates/gates for repeatable behavior.
+5. Validate with focused smoke.
+6. Update `.gse/evidence/YYYY-MM-DD.md`, goal map, and current slice.
+
+## Anti-Routes
+
+- Do not use GSE as a reason to ignore project rules.
+- Do not load every reference file by default.
+- Do not treat optional tools as hard prerequisites.
+- Do not claim a route succeeded without evidence.
+- Do not keep adding prose when a script or template would make the behavior repeatable.

package/references/spec-workflow.md

@@ -0,0 +1,66 @@
+# Spec Workflow
+
+Use specs to prevent agents from implementing vague intent.
+
+## Markdown Fallback
+
+Create `.gse/changes/<change-id>/` with:
+
+```text
+brief.md       # why and user outcome
+spec.md        # behavior and acceptance
+design.md      # approach, state, risk, privacy
+tasks.md       # verifiable slices
+evidence.md    # proof and verification
+review.md      # review findings and closure
+execution-quality-pack.md # skills, tool routing, quality gates, evidence, closure
+```
+
+Portable helper:
+
+```text
+node <gse-skill>/scripts/init-change.mjs --target <project-root> --change-id <change-id> --level lite|standard|enterprise
+```
+
+Close and archive helper:
+
+```text
+node <gse-skill>/scripts/close-change.mjs --target <project-root> --change-id <change-id> --status result|verified|accepted
+```
+
+Closing a change moves `.gse/changes/<change-id>/` to `.gse/archive/<date>-<change-id>/` and appends a `change-archive` record to `.gse/evidence/index.jsonl`.
+
+## Optional OpenSpec Adapter
+
+Use OpenSpec when the project has it and the task changes a capability, API, state machine, data model, or public contract.
+
+Expected OpenSpec artifacts:
+
+- proposal.md
+- design.md
+- tasks.md
+- delta specs
+
+## Optional Comet Adapter
+
+Use Comet when a full change lifecycle is useful and the skill/tools are installed.
+
+Comet is suitable for Level 2 and Level 3 work that benefits from open, design, build, verify, archive phases.
+
+## Optional Superpowers Adapter
+
+Use Superpowers when complex planning, staged execution, subagent orchestration, or multi-pass review is available and useful.
+
+GSE's native fallback is `execution-quality-pack.md` plus `references/quality-gates.md`, `references/domain-quality-gates.md`, `references/agent-roles.md`, and `references/review.md`.
+
+Do not require Superpowers for Lite tasks or when the current host does not expose the needed tools.
+
+## Spec Quality Checklist
+
+- User outcome is explicit.
+- Non-goals are explicit.
+- Acceptance is testable.
+- Error and recovery behavior is covered for risky paths.
+- Privacy and permission boundaries are stated when relevant.
+- Evidence type is known before implementation.
+- Execution skills, tool routing, selected quality gates, and review closure are explicit for Standard and Enterprise work.