@t275005746/gse 0.1.1 → 0.2.0

package/references/final-form-roadmap.md

@@ -0,0 +1,203 @@
+# GSE Final Form Roadmap
+
+This roadmap defines the final product shape for GSE itself. It is the canonical continuation plan for GSE development after local v1 capability has been proven.
+
+The goal is not another patch cycle. Final form means a capable agent can enter a new or existing project, run a short GSE entry command, understand the project, select the next slice, execute with the right level of rigor, prove the result, and carry lessons forward without a long hand-written prompt.
+
+## Completion Definition
+
+GSE reaches final form when a new agent can enter any supported project and use `/gse continue` to obtain:
+
+- the project identity, current goal, active slice, and next action,
+- the required spec, quality gates, and evidence level,
+- the available tools, missing tools, role boundaries, and fallback path,
+- pending owner/external release evidence, plus any optional adapter claims that are not being made,
+- the learning rules that should affect the current run,
+- the exact checks needed before completion can be claimed.
+
+Broken state, stale evidence, unsupported tool claims, noisy risk lists, and missing host/runtime evidence must be surfaced before implementation begins.
+
+## Final Form Priorities
+
+| Priority | Area | Outcome | Acceptance |
+|---|---|---|---|
+| P0 | Short entry takeover | `/gse continue` replaces long goal prompts for mature projects | A project with `.gse/` returns current slice, next action, claim-boundary evidence, and required checks through the portable runner; host-native command evidence is recorded only when a specific host adapter claims it |
+| P1 | State system | Project state is readable, compact, repairable, and not a risk dump | State separates current summary, active slice, top risks, blocked gates, next checks, and archived risk history |
+| P2 | Evidence gate | Claims cannot outrun evidence | Evidence index validity is a preflight gate; bad JSONL, stale records, and downgraded UI/browser proof are labeled before close |
+| P3 | Spec and change lifecycle | GSE provides OpenSpec-style change control without requiring OpenSpec | Change packs move through proposed, active, implemented, verified, accepted, and archived states with goal-map links |
+| P4 | Roles and subagents | GSE provides Superpowers-style execution discipline without requiring a specific subagent host | Planner, locator, implementer, verifier, reviewer, doc/evidence, and release roles have dispatch packets and fallback checklists; process skills do not prove real host dispatch |
+| P5 | Tool and quality gates | Tool use is fast, explicit, and project-aware | LSP/index, browser, Playwright, MCP, CI, package manager, Windows shell, sparse checkout, UTF-8, and project custom gates are preflighted when relevant |
+| P6 | Learning automation | Repeated failures become guards | Lessons dedupe, classify severity, and promote into project quality gates, templates, scripts, or skill updates |
+| P7 | Project init and adapters | New projects get the right scaffold without heavy prerequisites | Lite, Standard, and Enterprise scaffolds create `.gse/` plus optional host pointers for `.codex`, `.claude`, `.mcp`, and similar folders |
+| P8 | Release and distribution | GSE is installable, auditable, and maintainable as an open-source skill product | npm/package install, GitHub release, public CI, security contact, repository settings, registry/marketplace records, bilingual docs, checksums/signing, and update paths are verified or honestly gated |
+| P9 | Benchmark and drills | GSE remains competitive with mature engineering skills | Regular audits compare against OpenSpec, Superpowers/BMAD-style roles, Comet-style phase discipline, and real projects such as AION and MuseFlow |
+| P10 | Final acceptance | Final claims are backed by real evidence at the right claim level | AION doctor, MuseFlow doctor, new-project bootstrap, `/gse continue`, evidence repair, state compaction, role dispatch, learning promotion, package publication, public CI, and portable command execution pass; host-native invocation is optional per host adapter and must be recorded before that adapter claims it |
+
+## First Execution Wave
+
+1. Done: make `/gse continue` run a hard preflight: state JSON, evidence index, project profile, quality gates, canonical plan, stale risks, and pending owner/external release evidence when the target exposes it.
+2. Done: split `.gse/state.json` into a compact default view and an archived risk/decision history so active sessions do not inherit unreadable residual risk blocks.
+3. Done for continuation: promote evidence index validity from target-project doctor finding to blocking preflight for `/gse continue`; close-gate evidence index validation already remains in place.
+4. Done: add explicit evidence levels for UI/browser/API/CI/owner/release/external proof: `verified-unit`, `verified-component`, `verified-api`, `verified-browser`, `verified-ci`, `accepted-owner`, `accepted-release`, and `external-required`.
+5. Done: convert reusable lessons from AION and MuseFlow into guards: Windows shell syntax, sparse checkout staging, UTF-8-safe Chinese docs, stale evidence, browser-smoke downgrade labeling, no fake subagent dispatch, and non-interrupting cross-thread sync.
+
+## Final Form Execution Plan
+
+This plan turns the completion definition into ordered implementation waves. It is the working plan for GSE itself, not a project roadmap for projects that use GSE.
+
+### Wave 1 - Short Entry And State Control
+
+Outcome: mature projects can resume from a short `/gse continue` entry instead of a long hand-written prompt.
+
+Status: verified; the hard preflight, compact state packet, completion plan, project guards, explicit evidence levels, role fallback readiness, and state/evidence repair path are verified. Native host slash-command evidence is an optional adapter claim, not a GSE core completion gate.
+
+Completed slices:
+
+- Done: `completionPlan` gives future agents exact required close steps, required close commands, and active conditional commands for encoding, installed-sync, maintenance snapshot, release bundle, and session sync.
+- Done: completionPlan drill audit verifies clean worktrees have no false active conditionals and dirty docs/scripts/references/acceptance/evidence changes activate the expected close checks.
+- Done: state repair path provides `/gse repair`, `CP14`, and concrete repair actions for stale state, bad JSONL, missing evidence files, next-action drift, and overlong residual risks.
+- Done: `gateTaxonomy` separates core workflow blockers from release gates and host-adapter claim gates in `/gse continue` compact state.
+- Done: generated/noisy artifacts stay visible in `/gse continue` as ignored paths but no longer count as actionable changes or trigger conditional close commands by themselves.
+- Done: active residual risks and archived risk history are counted separately so `/gse continue` does not make historical risk archive entries look like current blockers.
+- Done: the human-facing `/gse continue` prompt is a short action packet with project, root, slice, next action, close summary, risk summary, gate boundary, and do-step instead of long explanatory prose.
+- Done: product-visible progress drift is surfaced through `compactState.productProgressDrift`, `CP22`, and a first-ranked `product-visible-recovery` next-slice candidate when repeated internal/component-level provenance or boundary slices risk replacing visible product workflow progress.
+- Done: product outcome gating is surfaced through `compactState.productOutcomeGate`, `CP23`, and a first-ranked `product-visible-recovery` candidate when a product project repeatedly opens support/internal slices without a named user-visible delta; a deliberate support slice can declare a narrow `supportSliceBoundary`; GSE self-development is classified as `skill` and is not forced through this product gate.
+
+Acceptance:
+
+- `/gse continue` shows current slice, next action, top risks, claim-boundary evidence, required checks, relevant guard rules, evidence status, and completion plan.
+- Bad evidence and stale state fail before implementation or return a repair action.
+- Default output stays compact; historical risk detail stays archived.
+
+### Wave 2 - Spec, Role, And Execution Discipline
+
+Outcome: GSE provides OpenSpec-style change control and Superpowers-style execution discipline without requiring either tool.
+
+Status: locally verified for portable execution discipline; role fallback packet outputs, no-fake-dispatch close checks, file-ownership/staged-artifact close checks, and host capability record audits are verified. Real-host dispatch evidence remains host-specific future evidence.
+
+Boundary: OpenSpec-style and Superpowers-style workflows define requirements, change control, execution discipline, and review quality. They do not provide native slash commands, subagent dispatch, browser tooling, MCP, LSP, CI, or host UI integration by themselves. GSE follows the same boundary: those capabilities are optional host adapters and must be recorded as host evidence before they are claimed.
+
+Required slices:
+
+- Change lifecycle hardening: every active change can be opened, verified, closed, archived, and linked back to the goal map.
+- Done: role packet execution fallback: planner, locator, implementer, verifier, reviewer, doc/evidence, and release roles have auditable packet outputs for sequential fallback.
+- Done: no-fake-dispatch guard: close gate blocks real-subagent claims unless the current host/tool status is verified.
+- Done: file ownership and dirty-worktree guard: close gate reports staged, unstaged, untracked, mixed, conflict, and generated/test artifact paths before close.
+
+Acceptance:
+
+- A real target project can run a change pack from open to archive.
+- Role packets work both with real subagents and sequential fallback.
+- Close gate rejects missing evidence, missing review, fake dispatch, and unrelated staged files when the project can expose that data.
+
+### Wave 3 - Learning To Guard Promotion
+
+Outcome: repeated user corrections and project failures become reusable engineering controls.
+
+Status: locally verified; learning capture, duplicate occurrence counting, deterministic promotion analysis, candidate-only promotion reports, `/gse continue` CP15 visibility, and learning drift detection for promoted-but-unenforced candidates are verified.
+
+Completed slices:
+
+- Done: learning classifier categorizes lessons by shell, encoding, evidence, browser, git, host-tool, project-rule, and release.
+- Done: duplicate learning capture increments `Occurrences` without appending noisy duplicate entries.
+- Done: promotion paths follow note -> checklist/template -> guard/quality gate -> script/skill.
+- Done: `/gse learn --promote` is read-only by default, `/gse learn --promote --execute` writes candidate-only `.gse/learning-promotions.md`, and `/gse continue` surfaces CP15 learning promotion status.
+
+Completed slices:
+
+- Done: drift audit detects when promoted learning candidates are not covered by project guards, quality gates, `/gse continue`, `/gse close`, or focused audit scripts.
+
+Acceptance:
+
+- A lesson can be recorded once, deduped, and promoted into a project guard with evidence.
+- `/gse continue` and `/gse close` both surface promoted high-severity guards.
+- AION/MuseFlow lessons are used as examples but no AION/MuseFlow-specific behavior is hardcoded.
+
+### Wave 4 - Tool And Host Runtime Adapters
+
+Outcome: GSE stays portable while using available tools aggressively.
+
+Completed slices:
+
+- Done: host capability audit records track native slash-command, browser, MCP, LSP, subagent, and CI status as `verified`, `documented`, `unknown`, `unavailable`, or `external-required`, with `/gse continue` `CP16` visibility and overclaim checks.
+- Done: target-project hardening drills run GSE doctor, `/gse continue`, close gate, host capability, and learning drift checks against configured real projects without mutating target worktrees.
+- Done: optional tool fallback policy audit verifies markdown fallback and claim boundaries across tool adapters, router, model routing, host adapters, project profile, generated command adapters, continue packet wiring, and validation profiles.
+
+Required slices:
+
+- Native slash-command evidence: record real host-native `/gse continue` invocation only when a host adapter claims native support.
+- Done: Browser/UI evidence policy: `scripts/audit-ui-browser-evidence-policy.mjs` verifies that `verified-component`, `verified-api`, `verified-browser`, screenshot/visual inspection rules, continue/close downgrade surfacing, and validation wiring stay aligned.
+
+Acceptance:
+
+- GSE never claims native host support from portable command evidence alone.
+- Browser/UI verification downgrade is labeled before close.
+- Host adapter docs point back to `.gse/` and do not duplicate canonical rules.
+
+### Wave 5 - Distribution, Public Trust, And Maintenance
+
+Outcome: GSE can be installed, audited, updated, and maintained as an open-source skill product.
+
+Required slices:
+
+- Public release evidence: repository settings, CI, security contact, registry/package channel, marketplace/catalog, release bundle, checksum/signing, and update path records.
+- Done: Installed skill sync: `scripts/audit-installed-sync.mjs` verifies fresh package output, package metadata/version preservation, source-root privacy, installed-copy hash parity, and installed-copy `/gse maintenance` smoke when `--installed-root` is supplied.
+- Done: Session sync records: `scripts/record-session-sync.mjs` and `scripts/audit-session-sync.mjs` make installed-copy refresh and active-session sync attempts auditable without treating notification as adoption.
+- Public docs hardening: keep README and bilingual docs concise, search-friendly, and free of defensive caveat bloat.
+- Done: Maintenance cadence: `references/maintenance-cadence.md`, `/gse maintenance`, and `scripts/audit-maintenance-cadence.mjs` verify benchmark audit, drift audit, dependency/security review, forward-test, target drill, public acceptance, and installed-skill sync coverage.
+- Done: Maintenance snapshot failure isolation: failed canonical `latest-maintenance-snapshot.json` writes are redirected to `latest-maintenance-snapshot.failed.json` so release-bundle and maintenance freshness loops keep the last passing canonical snapshot.
+
+Acceptance:
+
+- `validate-gse` passes the appropriate profile for the release stage.
+- Public acceptance rows are accepted only with real owner/external evidence.
+- A clean consumer project can install GSE, run `gse status`, initialize `.gse/`, and execute `/gse continue` through the portable runner.
+
+## Current Final-Form Gap List
+
+These items should drive future slices only when the claim is being made:
+
+- Short entry takeover is verified through the portable runner; `/gse continue` now exposes a compact action prompt, `completionPlan`, `gateTaxonomy`, generated/noisy ignored paths, active-versus-archived risk counts, product-visible progress drift warnings, and product outcome gating for product projects. Real host-native slash-command evidence is optional per host adapter.
+- Project guards, learning promotion candidates, learning drift status, no-fake-dispatch/file-ownership close checks, host capability records, and target-project hardening drills now surface or execute through portable audits; AION/MuseFlow drill warnings remain project-local readiness signals, not GSE hard failures.
+- Evidence index validity is a hard preflight; evidence level granularity, state/evidence repair actions, and conservative historical evidence-level backfill are implemented.
+- Role fallback packets and host capability records are auditable through scaffold, `/gse continue`, and focused audits; real subagent dispatch still needs current host evidence.
+- Process skills such as OpenSpec, Superpowers, Comet, and GSE provide workflow discipline and portable artifacts; they do not satisfy host-native slash-command, subagent, browser, MCP, LSP, CI, or host UI evidence rows.
+- Learning capture, occurrence counting, classification, candidate promotion, candidate drift detection, and read-only target-project hardening drills are locally verified; remaining gaps are project-specific product evidence and external host evidence.
+- Public/package release mechanics, browser/UI evidence policy, maintenance cadence, installed/package sync freshness checks, active-session sync records, and portable command execution are verified; optional host-native slash-command evidence is recorded only for hosts that actually expose native support.
+- Failed canonical maintenance snapshot writes are isolated from the last passing snapshot; `.failed.json` is the diagnostic surface for failed runs.
+
+## Goal Mode Operating Contract
+
+Use this when continuing GSE itself in a goal-mode session:
+
+```text
+Goal: implement GSE final form as a portable, installable, evidence-driven engineering skill for long-running agent-assisted software projects.
+
+Workspace:
+<path-to-gse-repo>
+
+Start:
+1. Read the installed GSE `SKILL.md`.
+2. Read .gse/gse-design-master-plan.md, .gse/goal-map.md, .gse/current-slice.md, .gse/state.json, and references/final-form-roadmap.md.
+3. Continue from the current slice and the highest-priority unfinished Final Form roadmap item.
+4. Keep GSE generic. Do not add AION-only or MuseFlow-only behavior; use them as drills and evidence targets.
+
+Loop:
+Goal -> Spec -> Execute -> Evidence -> Learn.
+
+Slice rule:
+Do one verifiable slice at a time. Each slice must state outcome, scope, acceptance, evidence, risk, and next action. Prefer executable scripts, templates, and gates over prose-only rules.
+
+Verification:
+Run the smallest focused audit that proves the slice. For docs-only final-form routing changes, run audit-final-form-roadmap, roadmap consistency, JSON/UTF-8 sanity, and a smoke validation profile. For release or package claims, run the matching release/package audit.
+
+Evidence:
+Append evidence to .gse/evidence/YYYY-MM-DD.md and .gse/evidence/index.jsonl. Do not claim public, native host, marketplace, registry, CI, or owner acceptance without matching accepted records.
+
+Completion:
+A slice is complete only after focused validation passes, evidence is recorded, state/current-slice/goal-map are updated, and the changes are committed.
+```
+
+## Claim Boundary
+
+This roadmap is a contract for final-form development, not proof for every optional adapter claim. The live claim boundary remains `references/final-readiness.md` plus `scripts/audit-final-readiness.mjs`.

package/references/final-readiness.md

@@ -39,7 +39,7 @@ The table below describes the baseline/status source for each row. The current t
 | Marketplace approval | real marketplace/catalog approval or publication evidence | record-driven external gate |
 | Portable command execution | `run-gse-command.mjs` command semantics audit | verified |
 | Host adapters | generated adapter files and compatibility matrix audit | verified |
-| Native slash command | verified host invocation record with native slash support | record-driven external gate |
+| Native slash command | optional per-host adapter claim; verified only if a host invocation record proves native slash support | not claimed by GSE core |
 | Other host runtime invocation | verified invocation records per host | record-driven external gate |
 
 Do not read the baseline column as live status. For example, once the owner-selected license record is accepted, the audit reports `License decision` as `verified` even though the row remains an owner-gated claim type.
@@ -52,7 +52,7 @@ node <gse-skill>/scripts/audit-final-readiness.mjs --root <gse-skill>
 
 The audit must report external and owner gates as incomplete unless corresponding records exist. It is valid for the audit to pass while still reporting `owner-required` or `external-required`; passing means the matrix is honest and complete, not that every external gate is satisfied.
 
-Accepted owner/external records promote final rows only when the record contains accepted evidence and the relevant boundary proof. For example, a public CI row requires an accepted public CI run record with a successful conclusion and required-check proof; a registry row requires accepted publication evidence with registry proof; native slash command support requires a host invocation record that proves native slash-command support.
+Accepted owner/external records promote final rows only when the record contains accepted evidence and the relevant boundary proof. For example, a public CI row requires an accepted public CI run record with a successful conclusion and required-check proof; a registry row requires accepted publication evidence with registry proof. Native slash command support is a per-host optional adapter claim, not a GSE core completion gate; claim it only after a host invocation record proves native slash-command support.
 
 Use the promotion audit to verify that this path still works:
 
@@ -81,4 +81,4 @@ GSE can be described as publicly accepted only after:
 - public repository settings evidence exists when a public source repository is claimed,
 - public CI run evidence exists when public CI is claimed,
 - registry or marketplace publication evidence exists when those channels are claimed,
-- native slash-command support is recorded per host before it is claimed.
+- native slash-command support is recorded per host before it is claimed by that host adapter.

package/references/host-adapters.md

@@ -2,11 +2,13 @@
 
 Use this when a project needs GSE to work across Codex, Claude Code, Hermes/AION-style runtimes, WorkBuddy, Copilot-style agents, Gemini-style agents, or another agent host. Use `references/compatibility.md` to check host support status and adoption evidence before making capability claims.
 
-## Core Rule
-
-`.gse/` is the portable source of truth. Host-specific folders are adapters.
-
-Adapters may expose commands, hooks, skills, MCP servers, indexes, or local UI metadata for one host, but they must point back to `.gse/` for project policy, goals, evidence, quality gates, and learning rules.
+## Core Rule
+
+`.gse/` is the portable source of truth. Host-specific folders are adapters.
+
+Adapters may expose commands, hooks, skills, MCP servers, indexes, or local UI metadata for one host, but they must point back to `.gse/` for project policy, goals, evidence, quality gates, and learning rules.
+
+Process skills such as OpenSpec, Superpowers, Comet, and GSE can define workflow discipline, specs, roles, evidence, and quality gates. They do not create host-native slash commands, real subagent dispatch, browser automation, MCP servers, LSP indexes, CI runners, or host UI integration. Treat those as host capabilities and verify them through records before claiming support.
 
 ## Adapter Decision
 
@@ -17,7 +19,7 @@ Create or update a host adapter only when at least one condition is true:
 - A host-specific capability needs a short pointer to `.gse/` to avoid duplicate policy.
 - A migration is needed from an existing `.claude/`, `.codex/`, `.agents/`, or runtime-specific workflow into `.gse/`.
 
-Do not create host folders just for decoration. If the host capability is unknown, document it as `unknown` in `.gse/project-profile.md` or `.gse/tooling.md`.
+Do not create host folders just for decoration. If the host capability is unknown, document it as `unknown` in `.gse/project-profile.md`, `.gse/tooling.md`, or `.gse/host-capabilities.md`.
 
 ## Supported Host Shapes
 
@@ -75,9 +77,9 @@ node <gse-skill>/scripts/audit-host-runtime-invocation-drill.mjs --root <skill-o
 
 The drill writes temporary records for Claude, Codex, Hermes/AION-style, WorkBuddy, and generic hosts, then audits native versus portable evidence counts. It proves the record/audit mechanics only; it does not prove real host runtime support.
 
-Generated adapters are not runtime proof. A host capability becomes verified only when a persistent host invocation record exists and the audit can parse it.
-
-Minimum fields:
+Generated adapters are not runtime proof. A host capability becomes verified only when a persistent host invocation record exists and the audit can parse it.
+
+Minimum fields:
 
 - Host name and adapter path.
 - Source of truth: always `.gse/` unless the project explicitly says otherwise.
@@ -85,7 +87,33 @@ Minimum fields:
 - Unverified or unavailable capabilities.
 - How to start meaningful work in this host.
 - Safety and permissions.
-- Drift check owner or cadence.
+- Drift check owner or cadence.
+
+## Host Capability Records
+
+Use `.gse/host-capabilities.md` to keep a compact, auditable status table for host-native and tool capabilities:
+
+- `native-slash-command`
+- `browser`
+- `mcp`
+- `lsp`
+- `subagent`
+- `ci`
+
+Status vocabulary: `verified`, `documented`, `unknown`, `unavailable`, `external-required`.
+
+Rules:
+
+- `verified` needs concrete project or host evidence.
+- Native slash-command support cannot be verified from portable `run-gse-command.mjs` output.
+- `documented` and `external-required` rows must include a claim boundary.
+- Missing records are a continuation warning for new projects; invalid or overclaimed records fail the host capability audit.
+
+Audit command:
+
+```text
+node <gse-skill>/scripts/audit-host-capabilities.mjs --target <project-root> --json
+```
 
 ## Tool Status Rules
 

package/references/learning-system.md

@@ -21,15 +21,31 @@ Learnings keep long projects from repeating mistakes.
 
 Use `references/drift-audit.md` when a repeated lesson suggests stale docs, stale project-profile facts, stale host adapters, stale tool assumptions, or stale evidence state.
 
-- First occurrence: learning note.
-- Second occurrence: checklist or template update.
-- Third occurrence: project rule or quality gate.
-- Fifth occurrence: script, test, or dedicated skill.
+- First occurrence: learning note.
+- Second occurrence: checklist or template update.
+- Third occurrence: project guard, project rule, or quality gate.
+- Fifth occurrence: script, test, or dedicated skill.
+
+Use `scripts/audit-learning-promotion.mjs --target <project-root> --json` to classify and count repeated lessons. The audit is read-only by default. Use `/gse learn --promote --execute` only to write `.gse/learning-promotions.md` candidate output; it does not mutate `.gse/project-guards.md`, `.gse/quality-gates.md`, templates, scripts, or skill files without a deliberate follow-up change.
+
+Use `scripts/audit-learning-drift.mjs --root <gse-skill> --target <project-root> --json` after promotion analysis. It checks whether promoted guard or script candidates are covered by project guards, quality gates, `/gse continue`, `/gse close`, or a focused audit script. Uncovered high-severity candidates are surfaced as warnings so the next slice can deliberately promote them.
+
+Promotion categories:
+
+- `shell`: shell syntax, host command behavior, Windows/Unix command differences.
+- `encoding`: UTF-8, mojibake, localized document handling.
+- `evidence`: JSONL, evidence levels, stale records, close gates.
+- `browser`: browser smoke, Playwright, screenshot, component-test downgrade.
+- `git`: sparse checkout, staging, commit boundaries.
+- `host-tool`: subagents, MCP, LSP, native slash commands, host runtime claims.
+- `project-rule`: canonical plans, AGENTS.md, local project conventions.
+- `release`: CI, registry, marketplace, security contact, release evidence.
 
 ## Suggested Stores
 
-- `.gse/learnings.md` for portable project lessons.
-- `.learnings/` when the project already uses that convention.
-- `AGENTS.md` for durable project rules.
-- ADRs for architectural decisions.
+- `.gse/learnings.md` for portable project lessons.
+- `.gse/project-guards.md` for recurring preflight rules promoted from lessons.
+- `.learnings/` when the project already uses that convention.
+- `AGENTS.md` for durable project rules.
+- ADRs for architectural decisions.
 

package/references/maintenance-cadence.md

@@ -0,0 +1,51 @@
+# GSE Maintenance Cadence
+
+GSE final form requires recurring checks, not only one-time release proof. This cadence keeps benchmark coverage, drift detection, security review, forward testing, and target-project drills visible while host-native slash-command evidence remains an external gate.
+
+## Cadence Table
+
+| Area | Trigger | Minimum Cadence | Evidence | Command |
+|---|---|---|---|---|
+| Benchmark audit | Non-trivial GSE capability change or new comparable engineering skill | Monthly or before release | `.gse/benchmark-audits/` entry or roadmap update | `node scripts/audit-final-form-roadmap.mjs --root . --json` |
+| Drift audit | Project guard, learning, adapter, command, or state model changes | Weekly or before close | Learning drift and state freshness output | `node scripts/audit-learning-drift.mjs --root . --target . --json` |
+| Dependency and security review | Release, install, package, registry, CI, or external input changes | Monthly or before release | Release trust, CI readiness, and public acceptance outputs | `node scripts/audit-release-trust.mjs --root . --json` |
+| Forward test | Non-trivial routing, command, scaffold, validation, or package change | Before release and after major workflow changes | Fixture or fresh-session forward-test evidence | `node scripts/forward-test-gse.mjs --root . --json` |
+| Target-project hardening drill | GSE adoption, continue, close, host capability, or learning behavior changes | Weekly or before public release | Read-only target drill output | `node scripts/audit-target-hardening-drills.mjs --root . --json` |
+| Public acceptance doctor | Public release, registry, marketplace, host, or owner evidence changes | Before release or public claim | Pending owner/external gate report | `node scripts/audit-public-acceptance-readiness.mjs --root . --json` |
+| Command runner smoke | `/gse` command routing, portable command wrapper, or short-entry behavior changes | Every command-router change | Portable runner output from `scripts/run-gse-command.mjs` | `node scripts/run-gse-command.mjs --root . --target . --command "/gse maintenance" --json --compact` |
+| Installed skill sync | Any capability upgrade shipped from source to installed skill | Every capability upgrade | Installed-copy hash comparison and command smoke from `scripts/audit-installed-sync.mjs` | `node scripts/audit-installed-sync.mjs --root . --installed-root <installed-skill-dir> --json` |
+| Active session sync | Any capability upgrade that should reach active GSE-using sessions | Every capability upgrade when active sessions exist | Honest sent, archived, unavailable, failed, or skipped records from `scripts/record-session-sync.mjs` plus `scripts/audit-session-sync.mjs` | `node scripts/audit-session-sync.mjs --root . --require-installed --require-thread <thread-id> --json` |
+
+## Maintenance Snapshot
+
+Use a snapshot when the goal is to prove that the recurring checks actually ran, not only that the cadence is documented.
+
+```powershell
+node scripts/generate-maintenance-snapshot.mjs --root . --target . --installed-root <installed-skill-dir> --execute --json
+```
+
+The canonical output is `.gse/maintenance/latest-maintenance-snapshot.json` plus a Markdown sibling. Without `--installed-root`, the installed-sync row is package-only and must not be used as installed-copy freshness proof.
+
+For an installed package smoke, use package mode so source-worktree-only roadmap and release-bundle freshness checks do not become false blockers:
+
+```powershell
+node scripts/generate-maintenance-snapshot.mjs --root <installed-skill-dir> --target <installed-skill-dir> --package-smoke --skip-release-bundle --json
+```
+
+Package smoke proves the installed copy can run the maintenance command set. The source repository remains responsible for canonical roadmap, release bundle, and installed-root freshness evidence.
+
+## Close Rule
+
+Maintenance evidence is not a substitute for native host evidence, public CI, marketplace approval, or owner acceptance. It only proves that GSE has a repeatable upkeep loop and that remaining external gates stay visible.
+
+Before claiming a maintenance-sensitive slice complete, run:
+
+```powershell
+node scripts/audit-maintenance-cadence.mjs --root . --json
+node scripts/generate-maintenance-snapshot.mjs --root . --target . --installed-root <installed-skill-dir> --execute --json
+node scripts/audit-maintenance-snapshot.mjs --root . --json
+node scripts/run-gse-command.mjs --root . --target . --command "/gse maintenance" --json --compact
+node scripts/audit-installed-sync.mjs --root . --installed-root <installed-skill-dir> --json
+node scripts/audit-session-sync.mjs --root . --json
+node scripts/run-validation-profile.mjs --target . --profile lite --json
+```

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/quality-gates.md

@@ -6,13 +6,19 @@ Pick gates by task risk.
 
 - Outcome matches request.
 - Scope did not expand silently.
-- Acceptance has evidence.
-- Evidence status uses `evidence-taxonomy.md`: result, verified, or accepted.
-- Do not claim `verified` or `accepted` when evidence only proves `result`.
-- Dirty worktree contains only intended files; use `references/file-ownership.md` when ownership or pre-existing changes are unclear.
+- Acceptance has evidence.
+- Evidence status uses `evidence-taxonomy.md`: result, verified, or accepted.
+- Evidence level uses `evidence-taxonomy.md`: `result`, `verified-unit`, `verified-component`, `verified-api`, `verified-browser`, `verified-ci`, `accepted-owner`, `accepted-release`, or `external-required`.
+- Do not claim `verified` or `accepted` when evidence only proves `result`.
+- Do not describe `verified-component` or `verified-api` as `verified-browser`; record a downgrade when browser proof was required but only component/API proof ran.
+- Dirty worktree contains only intended files; use `references/file-ownership.md` when ownership or pre-existing changes are unclear.
+- Close checks must surface role-dispatch honesty, staged/unstaged/untracked worktree state, and staged generated/test artifacts before a slice is called complete.
 - Final answer states evidence and remaining risk.
-- Use `references/recovery.md` when work is interrupted, verification fails, rollback/resume decisions are needed, or another agent/session must continue.
-- Use `references/review.md` when task risk requires spec compliance, code quality, architecture drift, security/privacy, regression, or evidence review.
+- Use `references/recovery.md` when work is interrupted, verification fails, rollback/resume decisions are needed, or another agent/session must continue.
+- Check `.gse/project-guards.md` through `/gse continue` or `scripts/audit-project-guards.mjs` when recurring lessons may affect the slice.
+- Check `.gse/host-capabilities.md` through `/gse continue` or `scripts/audit-host-capabilities.mjs` before claiming native slash-command, browser, MCP, LSP, subagent, or CI support.
+- Check learning drift through `/gse continue` or `scripts/audit-learning-drift.mjs` before closing repeated-failure lessons as enforced.
+- Use `references/review.md` when task risk requires spec compliance, code quality, architecture drift, security/privacy, regression, or evidence review.
 - Use `references/domain-quality-gates.md` when task risk involves security/privacy, performance/cost, accessibility, resilience/recovery, UI/browser, API/state, data/migration, model/tool routing, or release/operations concerns.
 - Use `references/architecture-health.md` when the task touches structural boundaries, coupling, source-of-truth drift, ownership, dependency/security risk, performance/resilience, migration, or release impact.
 - Use `references/forward-test.md` for non-trivial GSE skill, scaffold, router, role, adapter, release, recovery, or packaging changes.
@@ -63,11 +69,12 @@ node <gse-skill>/scripts/run-validation-profile.mjs --target <project-root> --pr
 
 Use this runner when a host, user, or future agent needs a stable command instead of hand-selecting individual audit scripts.
 
-## UI Gates
-
-- Component test or browser smoke for visible behavior.
-- Screenshot or visual inspection for layout-sensitive work.
-- Loading, empty, error, success, retry, and cancelled states covered when relevant.
+## UI Gates
+
+- Component test or browser smoke for visible behavior.
+- Screenshot or visual inspection for layout-sensitive work.
+- Use `verified-component` for component-only UI proof and `verified-browser` for browser/screenshot-backed UI proof.
+- Loading, empty, error, success, retry, and cancelled states covered when relevant.
 
 ## Agent/Product Gates
 

package/references/role-dispatch-fallback.md

@@ -0,0 +1,54 @@
+# Role Dispatch Fallback
+
+Use this reference when real subagent tools are unavailable, unknown, or not appropriate for the current slice.
+
+GSE must never turn role names into fake delegation. A role packet is evidence that the work boundary was explicit; it is not evidence that a real subagent ran unless the host produced current dispatch evidence.
+
+## Required Roles
+
+The portable fallback set is:
+
+| Role | Purpose | Default write access | Fallback output |
+|---|---|---|---|
+| Planner | Define outcome, scope, acceptance, evidence, risk, and next action. | docs/state only | Slice plan with non-goals and selected gates |
+| Locator | Locate files, symbols, commands, existing tests, and ownership boundaries. | read-only | File/function/test map and relevant patterns |
+| Implementer | Make the bounded code or document change. | assigned files only | Diff summary and files changed |
+| Verifier | Run focused tests, smokes, audits, or structural checks. | evidence/test output only | Commands, results, evidence level, residual risk |
+| Reviewer | Review spec compliance, regression risk, quality, and missing tests. | read-only | Findings or explicit no-findings report |
+| Docs/Evidence | Record slice evidence, state changes, release notes, and learnings. | docs/evidence only | Evidence record and state/doc update summary |
+| Release | Check release, public, owner, CI, package, and host-runtime boundaries. | docs/release only | Release readiness and external gate summary |
+
+## Fallback Packet Requirements
+
+Every auditable role packet, whether real or sequential, must state:
+
+- Execution mode: `real-subagent`, `sequential-role`, or `handoff-session`.
+- Real delegation used: `yes` or `no`.
+- Host/tool used and tool status.
+- Fallback reason when real delegation is not used.
+- Role, objective, allowed files, forbidden files, and expected output.
+- Role output evidence.
+- Verification command or check.
+- Evidence level.
+- Stop condition.
+- Claim boundary.
+
+## Claim Boundary
+
+- `real-subagent` means a current host dispatch tool created an agent/task and returned evidence.
+- `sequential-role` means the main agent executed the role checklist locally.
+- `handoff-session` means another human or agent session owns the work after handoff.
+- File/tool parallelism is not subagent dispatch.
+- A role packet without dispatch evidence can still prove disciplined fallback, but it cannot prove real multi-agent execution.
+
+## Close Rule
+
+Before a slice closes, the coordinator should be able to answer:
+
+1. Which roles were required for this slice?
+2. Which roles ran as real delegation, sequential fallback, or handoff?
+3. What files or evidence did each role touch?
+4. What verification or review did each role produce?
+5. What claim must not be made because a tool was unavailable?
+
+`scripts/audit-close-gate.mjs` enforces the no-fake-dispatch boundary when `.gse/agents/role-fallback-packets.md` is present: a row that says real delegation was used must also have verified tool status.

package/references/tool-adapters.md

@@ -1,6 +1,8 @@
 # Tool Adapters
 
-GSE has few hard requirements. Tools enhance the workflow when available.
+GSE has few hard requirements. Tools enhance the workflow when available.
+Use markdown fallback when optional tools are unavailable.
+Do not treat optional tools as hard prerequisites.
 
 ## Minimum Tools
 
@@ -31,7 +33,7 @@ Avoid broad reads of generated outputs, logs, lockfiles, or historical archives
 
 Use `references/drift-audit.md` when recorded tool status, command assumptions, MCP, LSP/index, browser, CI, package manager, or deployment facts may be stale.
 
-Use `project-profile.md` to record tool connections and status.
+Use `.gse/project-profile.md`, `.gse/tooling.md`, and `.gse/host-capabilities.md` to record tool connections and status.
 
 Status vocabulary:
 
@@ -40,7 +42,15 @@ Status vocabulary:
 - `unknown`: not confirmed.
 - `unavailable`: expected but missing or failing.
 
-Project-specific commands and standards override generic recommendations. If the project says to use `pnpm`, `bun`, `make`, a custom smoke script, a specific LSP/index, or a private MCP server, follow that after verifying it is present or documenting its status.
+Project-specific commands and standards override generic recommendations. If the project says to use `pnpm`, `bun`, `make`, a custom smoke script, a specific LSP/index, or a private MCP server, follow that after verifying it is present or documenting its status.
+
+For the standard host/tool capability table, run:
+
+```text
+node <gse-skill>/scripts/audit-host-capabilities.mjs --target <project-root> --json
+```
+
+This audit checks native slash-command, browser, MCP, LSP/index, subagent dispatch, and CI rows. It labels missing records as a warning, but fails invalid statuses, `verified` rows without evidence, and native slash-command overclaims based only on portable command output.
 
 ## Model Routing