@t275005746/gse 0.1.0 → 0.1.1

package/references/adoption-recipes.md

@@ -1,171 +1,171 @@
-# Adoption Recipes
-
-Use this when applying GSE to a project or updating an existing GSE installation.
-
-These recipes are host-neutral. They do not certify arbitrary repositories, install external tools, publish GSE, or verify host runtime capabilities. Treat project and host capabilities as `unknown` until checked in that project/session.
-
-## Recipe 1: Fresh Project Install
-
-Use when a project has no `.gse/` folder yet.
-
-Steps:
-
-1. Read project rules first: `AGENTS.md`, `CLAUDE.md`, README, or equivalent.
-2. Choose mode from `references/task-levels.md` and `references/project-bootstrap.md`: `lite`, `standard`, or `enterprise`.
-3. Run:
-
-```text
-node <gse-skill>/scripts/init-project.mjs --target <project-root> --mode <mode>
-```
-
-4. Inspect generated `.gse/state.json`, `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/quality-gates.md`, `.gse/tooling.md`, and `.gse/evidence/index.jsonl`.
-5. Record project-specific commands, standards, permissions, and owners in `.gse/project-profile.md`.
-6. Run the smallest project verification that proves the install is usable, such as checking files exist and reading `.gse/README.md`.
-   Prefer the target doctor when available:
-
-```text
-node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
-```
-
-7. Record residual risk: commands, CI, browser, MCP, LSP, subagents, models, and release paths remain `unknown` until executed.
-
-Evidence status: `result` when files exist; `verified` only after focused project inspection or smoke proves the generated workflow is usable.
-
-## Recipe 2: Existing Repo Adoption
-
-Use when a repository already has rules, scripts, CI, host folders, or partial `.gse/` files.
-
-Steps:
-
-1. Read project rules and existing workflow docs before generating anything.
-2. Run discovery without writing:
-
-```text
-node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
-```
-
-3. Treat discovered scripts/configs as `documented`, not `verified`, until the commands actually run.
-4. If `.gse/project-profile.md` already exists, do not overwrite it without explicit `--force` and a reason. Do not overwrite existing project workflow files just because GSE has defaults.
-5. If writing is approved, use:
-
-```text
-node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --write
-```
-
-6. Preserve project-specific standards, host adapters, existing evidence logs, and owner decisions.
-7. Record whether adoption is `result`, `verified`, or `accepted` using `references/evidence-taxonomy.md`.
-
-Evidence status: `verified` for controlled fixture behavior when `scripts/audit-adoption.mjs` passes; real repos need project-specific evidence.
-
-## Recipe 3: Update Existing GSE
-
-Use when a project already follows GSE and the skill or project-local `.gse/` files need an update.
-
-Steps:
-
-1. Read `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/current-slice.md` if present, and host adapter notes.
-   Prefer `.gse/state.json` and `.gse/evidence/index.jsonl` when present because they are the machine-readable continuation state.
-2. Identify whether the update affects templates, scripts, host adapters, quality gates, release/recovery, or project rules.
-3. Preserve local project decisions. Do not replace project `.gse/` files with skill defaults unless the project owner approves.
-4. Run skill validation after updating the skill package:
-
-```text
-node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
-```
-
-5. Run project-local validation or smoke for the affected workflow.
-   For read-only workflow drift checks, run:
-
-```text
-node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
-```
-
-If the project predates `.gse/state.json` and `.gse/evidence/index.jsonl`, add only the missing machine-readable continuation files:
-
-```text
-node <gse-skill>/scripts/update-project-state.mjs --target <project-root>
-```
-
-6. Record changed files, migration/rollback notes, evidence status, residual risks, and next action in the project evidence log.
-
-Evidence status: `verified` only when the project-local update path and affected workflow have focused evidence.
-
-## Recipe 4: Host Adapter Adoption
-
-Use when a project needs Codex, Claude Code, Hermes/AION-style runtime, WorkBuddy, Copilot/Gemini-style, or custom host pointers.
-
-Steps:
-
-1. Read `references/compatibility.md` and `references/host-adapters.md`.
-2. Generate short command/pointer adapters only when the host has a real adapter location:
-
-```text
-node <gse-skill>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
-```
-
-`scripts/generate-host-adapter.mjs` is a legacy fixture helper for the older Codex/Claude markdown adapter smoke. Prefer `generate-command-adapter.mjs` for new project adoption.
-
-3. Keep `.gse/` as the source of truth. Do not copy goal maps, quality gates, or evidence into host folders.
-4. Mark host capabilities as `verified`, `documented`, `unknown`, or `unavailable` based on current evidence.
-5. Run `scripts/audit-host-adapters.mjs` for GSE fixture coverage, then run project-specific inspection for the target project.
-
-Evidence status: fixture generation can be `verified`; actual host runtime tools remain project/session-specific.
-
-## Recipe 5: CLI Or Package Project Adoption
-
-Use when a project is primarily a command-line tool, reusable package, SDK, plugin, or library rather than a web app.
-
-Steps:
-
-1. Read package docs and project rules before changing workflow files: `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, package manifest, and release notes if present.
-2. Run discovery first:
-
-```text
-node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
-```
-
-3. Treat `bin` entries, package scripts, publish commands, signing, registry, and shell integration as `documented` or `unknown` until a focused smoke proves them.
-4. Preserve package metadata, release notes, compatibility policy, and existing publish/rollback instructions.
-5. Prefer a small command smoke before broader tests, such as `npm run smoke`, `node ./bin/<name> --help`, `npm pack --dry-run`, or the project equivalent.
-6. Record exit-code behavior, changed files, package artifacts intentionally ignored, residual release risk, and next action.
-
-Evidence status: fixture coverage can be `verified`; real package install, registry access, publish permissions, global install, and shell completion require project-specific evidence.
-
-## Adoption Record
-
-Use this compact record in `.gse/evidence/` or the project evidence log:
-
-```text
-Adoption recipe:
-Project path:
-Mode or host:
-Project rules read:
-Commands run:
-Files created or changed:
-Preserved project-specific rules:
-Host/tool statuses:
-Validation evidence:
-Evidence status: result | verified | accepted | not ready
-Residual risk:
-Next action:
-```
-
-For real target-project evidence, use `assets/templates/target-adoption-evidence.md`. Keep discovered scripts and configs as `documented` until executed, and keep `Accepted by: not accepted` unless a real acceptance gate ran.
-
-Use `assets/templates/acceptance-execution-packet.md` before writing project-local `.gse/` artifacts or claiming owner-approved adoption acceptance.
-
-## Verification Commands
-
-Use only the commands that match the recipe and risk:
-
-```text
-node <gse-skill>/scripts/audit-project.mjs --root <gse-skill>
-node <gse-skill>/scripts/audit-adoption.mjs --root <gse-skill>
-node <gse-skill>/scripts/audit-command-adapters.mjs --root <gse-skill>
-node <gse-skill>/scripts/audit-host-adapters.mjs --root <gse-skill>
-node <gse-skill>/scripts/audit-fixtures.mjs --root <gse-skill>
-node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
-node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
-```
-
-These commands verify GSE fixtures and skill readiness. They do not certify arbitrary production repositories. Real adoption still needs project-specific inspection, focused smokes, and evidence.
+# Adoption Recipes
+
+Use this when applying GSE to a project or updating an existing GSE installation.
+
+These recipes are host-neutral. They do not certify arbitrary repositories, install external tools, publish GSE, or verify host runtime capabilities. Treat project and host capabilities as `unknown` until checked in that project/session.
+
+## Recipe 1: Fresh Project Install
+
+Use when a project has no `.gse/` folder yet.
+
+Steps:
+
+1. Read project rules first: `AGENTS.md`, `CLAUDE.md`, README, or equivalent.
+2. Choose mode from `references/task-levels.md` and `references/project-bootstrap.md`: `lite`, `standard`, or `enterprise`.
+3. Run:
+
+```text
+node <gse-skill>/scripts/init-project.mjs --target <project-root> --mode <mode>
+```
+
+4. Inspect generated `.gse/state.json`, `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/quality-gates.md`, `.gse/tooling.md`, and `.gse/evidence/index.jsonl`.
+5. Record project-specific commands, standards, permissions, and owners in `.gse/project-profile.md`.
+6. Run the smallest project verification that proves the install is usable, such as checking files exist and reading `.gse/README.md`.
+   Prefer the target doctor when available:
+
+```text
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+```
+
+7. Record residual risk: commands, CI, browser, MCP, LSP, subagents, models, and release paths remain `unknown` until executed.
+
+Evidence status: `result` when files exist; `verified` only after focused project inspection or smoke proves the generated workflow is usable.
+
+## Recipe 2: Existing Repo Adoption
+
+Use when a repository already has rules, scripts, CI, host folders, or partial `.gse/` files.
+
+Steps:
+
+1. Read project rules and existing workflow docs before generating anything.
+2. Run discovery without writing:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+3. Treat discovered scripts/configs as `documented`, not `verified`, until the commands actually run.
+4. If `.gse/project-profile.md` already exists, do not overwrite it without explicit `--force` and a reason. Do not overwrite existing project workflow files just because GSE has defaults.
+5. If writing is approved, use:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --write
+```
+
+6. Preserve project-specific standards, host adapters, existing evidence logs, and owner decisions.
+7. Record whether adoption is `result`, `verified`, or `accepted` using `references/evidence-taxonomy.md`.
+
+Evidence status: `verified` for controlled fixture behavior when `scripts/audit-adoption.mjs` passes; real repos need project-specific evidence.
+
+## Recipe 3: Update Existing GSE
+
+Use when a project already follows GSE and the skill or project-local `.gse/` files need an update.
+
+Steps:
+
+1. Read `.gse/project-profile.md`, `.gse/goal-map.md`, `.gse/current-slice.md` if present, and host adapter notes.
+   Prefer `.gse/state.json` and `.gse/evidence/index.jsonl` when present because they are the machine-readable continuation state.
+2. Identify whether the update affects templates, scripts, host adapters, quality gates, release/recovery, or project rules.
+3. Preserve local project decisions. Do not replace project `.gse/` files with skill defaults unless the project owner approves.
+4. Run skill validation after updating the skill package:
+
+```text
+node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
+```
+
+5. Run project-local validation or smoke for the affected workflow.
+   For read-only workflow drift checks, run:
+
+```text
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+```
+
+If the project predates `.gse/state.json` and `.gse/evidence/index.jsonl`, add only the missing machine-readable continuation files:
+
+```text
+node <gse-skill>/scripts/update-project-state.mjs --target <project-root>
+```
+
+6. Record changed files, migration/rollback notes, evidence status, residual risks, and next action in the project evidence log.
+
+Evidence status: `verified` only when the project-local update path and affected workflow have focused evidence.
+
+## Recipe 4: Host Adapter Adoption
+
+Use when a project needs Codex, Claude Code, Hermes/AION-style runtime, WorkBuddy, Copilot/Gemini-style, or custom host pointers.
+
+Steps:
+
+1. Read `references/compatibility.md` and `references/host-adapters.md`.
+2. Generate short command/pointer adapters only when the host has a real adapter location:
+
+```text
+node <gse-skill>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
+```
+
+`scripts/generate-host-adapter.mjs` is a legacy fixture helper for the older Codex/Claude markdown adapter smoke. Prefer `generate-command-adapter.mjs` for new project adoption.
+
+3. Keep `.gse/` as the source of truth. Do not copy goal maps, quality gates, or evidence into host folders.
+4. Mark host capabilities as `verified`, `documented`, `unknown`, or `unavailable` based on current evidence.
+5. Run `scripts/audit-host-adapters.mjs` for GSE fixture coverage, then run project-specific inspection for the target project.
+
+Evidence status: fixture generation can be `verified`; actual host runtime tools remain project/session-specific.
+
+## Recipe 5: CLI Or Package Project Adoption
+
+Use when a project is primarily a command-line tool, reusable package, SDK, plugin, or library rather than a web app.
+
+Steps:
+
+1. Read package docs and project rules before changing workflow files: `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, package manifest, and release notes if present.
+2. Run discovery first:
+
+```text
+node <gse-skill>/scripts/discover-project-profile.mjs --target <project-root> --json
+```
+
+3. Treat `bin` entries, package scripts, publish commands, signing, registry, and shell integration as `documented` or `unknown` until a focused smoke proves them.
+4. Preserve package metadata, release notes, compatibility policy, and existing publish/rollback instructions.
+5. Prefer a small command smoke before broader tests, such as `npm run smoke`, `node ./bin/<name> --help`, `npm pack --dry-run`, or the project equivalent.
+6. Record exit-code behavior, changed files, package artifacts intentionally ignored, residual release risk, and next action.
+
+Evidence status: fixture coverage can be `verified`; real package install, registry access, publish permissions, global install, and shell completion require project-specific evidence.
+
+## Adoption Record
+
+Use this compact record in `.gse/evidence/` or the project evidence log:
+
+```text
+Adoption recipe:
+Project path:
+Mode or host:
+Project rules read:
+Commands run:
+Files created or changed:
+Preserved project-specific rules:
+Host/tool statuses:
+Validation evidence:
+Evidence status: result | verified | accepted | not ready
+Residual risk:
+Next action:
+```
+
+For real target-project evidence, use `assets/templates/target-adoption-evidence.md`. Keep discovered scripts and configs as `documented` until executed, and keep `Accepted by: not accepted` unless a real acceptance gate ran.
+
+Use `assets/templates/acceptance-execution-packet.md` before writing project-local `.gse/` artifacts or claiming owner-approved adoption acceptance.
+
+## Verification Commands
+
+Use only the commands that match the recipe and risk:
+
+```text
+node <gse-skill>/scripts/audit-project.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-adoption.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-command-adapters.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-host-adapters.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-fixtures.mjs --root <gse-skill>
+node <gse-skill>/scripts/audit-target-project.mjs --target <project-root>
+node <gse-skill>/scripts/validate-gse.mjs --root <gse-skill>
+```
+
+These commands verify GSE fixtures and skill readiness. They do not certify arbitrary production repositories. Real adoption still needs project-specific inspection, focused smokes, and evidence.

package/references/agent-roles.md

@@ -1,49 +1,49 @@
-# Agent Roles
-
-Use roles to make multi-agent work predictable.
-
-## Coordinator
-
-Owns scope, task level, context selection, final integration, and final answer.
-
-Never delegates final judgment.
-
-## Product Analyst
-
-Clarifies user outcome, pain, audience, competitive baseline, and priority.
-
-## Architect
-
-Defines state, data flow, module boundaries, contracts, risks, and rollback.
-
-## Code Locator
-
-Read-only. Finds files, symbols, call chains, existing tests, and local patterns.
-
-## Builder
-
-Implements a bounded slice. Avoids unrelated refactors.
-
-## Reviewer
-
-Checks correctness, regressions, architecture drift, security, and missing tests using `references/review.md`.
-
-## QA
-
-Runs focused verification, browser smoke, API smoke, or screenshot checks.
-
-## Docs/Evidence
-
-Writes evidence, changelog notes, ADR links, and learning entries. Does not modify implementation unless explicitly assigned.
-
-## Dispatch Rules
-
-- Use real subagent tools only when exposed by the current host.
-- Give each agent a role, files allowed, expected output, and forbidden actions. Use `assets/templates/dispatch-packet.md` when the assignment needs durable boundaries or evidence.
-- Avoid parallel writes to the same files.
-- If subagents are unavailable, execute roles sequentially in the main session and say so.
-
-## File Ownership
-
-Use `references/file-ownership.md` before assigning write access, running parallel implementation, or editing in a dirty worktree. Keep locator, reviewer, and QA roles read-only unless explicitly assigned otherwise.
-
+# Agent Roles
+
+Use roles to make multi-agent work predictable.
+
+## Coordinator
+
+Owns scope, task level, context selection, final integration, and final answer.
+
+Never delegates final judgment.
+
+## Product Analyst
+
+Clarifies user outcome, pain, audience, competitive baseline, and priority.
+
+## Architect
+
+Defines state, data flow, module boundaries, contracts, risks, and rollback.
+
+## Code Locator
+
+Read-only. Finds files, symbols, call chains, existing tests, and local patterns.
+
+## Builder
+
+Implements a bounded slice. Avoids unrelated refactors.
+
+## Reviewer
+
+Checks correctness, regressions, architecture drift, security, and missing tests using `references/review.md`.
+
+## QA
+
+Runs focused verification, browser smoke, API smoke, or screenshot checks.
+
+## Docs/Evidence
+
+Writes evidence, changelog notes, ADR links, and learning entries. Does not modify implementation unless explicitly assigned.
+
+## Dispatch Rules
+
+- Use real subagent tools only when exposed by the current host.
+- Give each agent a role, files allowed, expected output, and forbidden actions. Use `assets/templates/dispatch-packet.md` when the assignment needs durable boundaries or evidence.
+- Avoid parallel writes to the same files.
+- If subagents are unavailable, execute roles sequentially in the main session and say so.
+
+## File Ownership
+
+Use `references/file-ownership.md` before assigning write access, running parallel implementation, or editing in a dirty worktree. Keep locator, reviewer, and QA roles read-only unless explicitly assigned otherwise.
+

package/references/architecture-health.md

@@ -1,101 +1,101 @@
-# Architecture Health
-
-Use this when a change may affect the long-term shape of a project, not only the immediate behavior. Architecture health checks look for structural drift that can make future work slower, riskier, or harder for agents to understand.
-
-## Trigger Conditions
-
-Run an architecture health scan when any of these are true:
-
-- A change crosses module boundaries, package boundaries, runtime boundaries, product boundaries, or host adapter boundaries.
-- A new subsystem, provider, model route, worker, storage layer, queue, browser/runtime path, or deployment path is added.
-- Repeated bugs suggest hidden coupling, unclear ownership, duplicated logic, or a missing source of truth.
-- A dependency, security boundary, permission model, migration, release path, or rollback path changes.
-- Performance, resilience, cancellation, retry, state recovery, or observability behavior is material to the slice.
-- Project docs, generated artifacts, code, and .gse/ records disagree about the intended design.
-
-Do not run a broad scan for tiny local edits unless the edit touches a structural boundary.
-
-## Scope Levels
-
-Pick the smallest scan that can prove the risk is understood.
-
-| Level | Use when | Minimum evidence |
-|---|---|---|
-| Lightweight local scan | One file, one module, one adapter, or one narrow workflow changed | Relevant files, nearest tests/checks, project rules that govern the area |
-| Subsystem scan | A feature crosses modules, storage/state, API/UI, worker/runtime, or tool boundaries | Call flow, data ownership, source-of-truth records, focused verification |
-| Broad architecture review | Large refactor, new platform capability, release/migration risk, recurring failures, or uncertain ownership | Architecture docs, ADRs, project profile, dependency/release notes, evidence and follow-up slices |
-
-## Scan Axes
-
-### Module Boundaries
-
-- Are module boundaries, package boundaries, runtime boundaries, and host adapter boundaries still clear?
-- Did the change import across layers in a way the project does not already allow?
-- Is shared behavior placed in the right owner instead of copied into callers?
-
-### Coupling And Cohesion
-
-- Did the change create tight coupling between UI, API, worker, storage, tools, models, or host-specific adapters?
-- Can a future agent change one concern without understanding unrelated concerns?
-- Are abstractions justified by repeated complexity or existing project patterns?
-
-### Source Of Truth Drift
-
-- Is there one source of truth for goals, specs, state, memory, routing, configuration, and evidence?
-- Do docs, code, scripts, templates, generated files, and .gse/ records agree?
-- Are compatibility names or legacy internal names contained behind adapters rather than exposed as product truth?
-
-### Dependency And Security Risk
-
-- Did dependencies, provider SDKs, MCP/tool integrations, or browser/runtime permissions change?
-- Are dependency and security assumptions verified, documented, or explicitly unknown?
-- Are secrets, raw provider payloads, hidden reasoning, and privileged tool traces excluded from user-visible or committed outputs?
-
-### Ownership And Change Control
-
-- Which module, team, role, or agent owns the changed behavior?
-- Are file ownership and multi-agent lock rules clear enough to prevent overlapping edits?
-- Does the change need an ADR, project-profile update, or future release note?
-
-### Performance And Resilience
-
-- Could the design add latency, heavy context loading, unnecessary worker paths, repeated browser loops, or expensive model routes?
-- Are cancellation, retry, timeout, recovery, idempotency, and duplicate prevention considered where relevant?
-- Is observability enough to diagnose failure without leaking sensitive data?
-
-### Migration And Release Impact
-
-- Does the change affect install, upgrade, data migration, backward compatibility, rollback, or release acceptance?
-- Are migration and release risks captured as decisions or follow-up slices rather than hidden assumptions?
-- Is the verification scope strong enough for the release risk?
-
-## Output Format
-
-Keep the output concise. Link to evidence instead of pasting long logs.
-
-```text
-Scan scope:
-Findings:
-Risks:
-Decisions needed:
-Follow-up slices:
-Evidence:
-```
-
-## Classification Rules
-
-- Findings are observed facts from code, docs, scripts, tests, or runtime behavior.
-- Risks are plausible future failures or maintenance costs that the current evidence does not eliminate.
-- Decisions needed are architecture choices that require owner, user, or project-standard confirmation.
-- Follow-up slices are bounded implementation or documentation steps that can be verified later.
-
-Do not label a guess as a finding. If evidence is indirect, record it as a risk or assumption and choose a follow-up slice.
-
-## Integration
-
-- Use references/review.md for the review axes and severity language.
-- Use references/quality-gates.md to decide whether architecture health is required for the task risk.
-- Use references/file-ownership.md when ownership, dirty worktree, or multi-agent overlap is unclear.
-- Use references/project-profile.md and project architecture docs as the source of project-specific standards.
-- Use references/release.md when architecture risk affects migration, rollback, compatibility, changelog/release notes, or release acceptance.
-- Use references/evidence-taxonomy.md to classify the final claim as result, verified, or accepted.
+# Architecture Health
+
+Use this when a change may affect the long-term shape of a project, not only the immediate behavior. Architecture health checks look for structural drift that can make future work slower, riskier, or harder for agents to understand.
+
+## Trigger Conditions
+
+Run an architecture health scan when any of these are true:
+
+- A change crosses module boundaries, package boundaries, runtime boundaries, product boundaries, or host adapter boundaries.
+- A new subsystem, provider, model route, worker, storage layer, queue, browser/runtime path, or deployment path is added.
+- Repeated bugs suggest hidden coupling, unclear ownership, duplicated logic, or a missing source of truth.
+- A dependency, security boundary, permission model, migration, release path, or rollback path changes.
+- Performance, resilience, cancellation, retry, state recovery, or observability behavior is material to the slice.
+- Project docs, generated artifacts, code, and .gse/ records disagree about the intended design.
+
+Do not run a broad scan for tiny local edits unless the edit touches a structural boundary.
+
+## Scope Levels
+
+Pick the smallest scan that can prove the risk is understood.
+
+| Level | Use when | Minimum evidence |
+|---|---|---|
+| Lightweight local scan | One file, one module, one adapter, or one narrow workflow changed | Relevant files, nearest tests/checks, project rules that govern the area |
+| Subsystem scan | A feature crosses modules, storage/state, API/UI, worker/runtime, or tool boundaries | Call flow, data ownership, source-of-truth records, focused verification |
+| Broad architecture review | Large refactor, new platform capability, release/migration risk, recurring failures, or uncertain ownership | Architecture docs, ADRs, project profile, dependency/release notes, evidence and follow-up slices |
+
+## Scan Axes
+
+### Module Boundaries
+
+- Are module boundaries, package boundaries, runtime boundaries, and host adapter boundaries still clear?
+- Did the change import across layers in a way the project does not already allow?
+- Is shared behavior placed in the right owner instead of copied into callers?
+
+### Coupling And Cohesion
+
+- Did the change create tight coupling between UI, API, worker, storage, tools, models, or host-specific adapters?
+- Can a future agent change one concern without understanding unrelated concerns?
+- Are abstractions justified by repeated complexity or existing project patterns?
+
+### Source Of Truth Drift
+
+- Is there one source of truth for goals, specs, state, memory, routing, configuration, and evidence?
+- Do docs, code, scripts, templates, generated files, and .gse/ records agree?
+- Are compatibility names or legacy internal names contained behind adapters rather than exposed as product truth?
+
+### Dependency And Security Risk
+
+- Did dependencies, provider SDKs, MCP/tool integrations, or browser/runtime permissions change?
+- Are dependency and security assumptions verified, documented, or explicitly unknown?
+- Are secrets, raw provider payloads, hidden reasoning, and privileged tool traces excluded from user-visible or committed outputs?
+
+### Ownership And Change Control
+
+- Which module, team, role, or agent owns the changed behavior?
+- Are file ownership and multi-agent lock rules clear enough to prevent overlapping edits?
+- Does the change need an ADR, project-profile update, or future release note?
+
+### Performance And Resilience
+
+- Could the design add latency, heavy context loading, unnecessary worker paths, repeated browser loops, or expensive model routes?
+- Are cancellation, retry, timeout, recovery, idempotency, and duplicate prevention considered where relevant?
+- Is observability enough to diagnose failure without leaking sensitive data?
+
+### Migration And Release Impact
+
+- Does the change affect install, upgrade, data migration, backward compatibility, rollback, or release acceptance?
+- Are migration and release risks captured as decisions or follow-up slices rather than hidden assumptions?
+- Is the verification scope strong enough for the release risk?
+
+## Output Format
+
+Keep the output concise. Link to evidence instead of pasting long logs.
+
+```text
+Scan scope:
+Findings:
+Risks:
+Decisions needed:
+Follow-up slices:
+Evidence:
+```
+
+## Classification Rules
+
+- Findings are observed facts from code, docs, scripts, tests, or runtime behavior.
+- Risks are plausible future failures or maintenance costs that the current evidence does not eliminate.
+- Decisions needed are architecture choices that require owner, user, or project-standard confirmation.
+- Follow-up slices are bounded implementation or documentation steps that can be verified later.
+
+Do not label a guess as a finding. If evidence is indirect, record it as a risk or assumption and choose a follow-up slice.
+
+## Integration
+
+- Use references/review.md for the review axes and severity language.
+- Use references/quality-gates.md to decide whether architecture health is required for the task risk.
+- Use references/file-ownership.md when ownership, dirty worktree, or multi-agent overlap is unclear.
+- Use references/project-profile.md and project architecture docs as the source of project-specific standards.
+- Use references/release.md when architecture risk affects migration, rollback, compatibility, changelog/release notes, or release acceptance.
+- Use references/evidence-taxonomy.md to classify the final claim as result, verified, or accepted.