@t275005746/gse 0.1.0 → 0.1.2

package/references/release.md

@@ -1,126 +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.
+# 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

@@ -1,141 +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.
+# 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/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.