USM

Appearance

usm/feedback-upstream-routing [built] ​

Scope-aware feedback routing — the generated feedback protocol, MCP tool, and docs page distinguish bugs in the consuming project (route per project policy/tracker) from bugs in the USM tool itself (route upstream), with the upstream URL literal and override. When the project tracker and upstream tracker are the same place (the USM repo itself), the protocol collapses to coherent single-tracker text instead of contradicting itself.

Status: built

Why this exists ​

Agents in downstream projects misattribute USM tool bugs to the project they are working in. The generated feedback protocol says 'Real bugs live in the issue tracker: <this repo>' with no scope distinction, so an agent hitting an update_feature data-loss bug files (or gates) it against daingerdainger-com instead of the USM repo. Tool bugs need explicit upstream routing with the exact target.

Design decisions ​

default-upstream-hardcoded ​

Decision: Default upstream tracker is the canonical USM repo, overridable via feedback.upstream_tracker

Rationale: Consumers should not need configuration to get correct routing; forks/rebrands can override. Optional schema field only — no breaking change.

classification-instructions-not-detection ​

Decision: Teach scope classification via instructions rather than automatic detection in the MCP tool

Rationale: Classification requires judgment about blast radius; the agent (or human at the gate) is better placed than a heuristic on the summary string. The tool only nudges when a USM tool bug seems likely.

How it works ​

Agent classifies a bug by blast radius (agent-classifies-scope) ​

When an agent discovers a bug, it first determines whether the fault is in the project or in the USM tool itself.

  1. Detect — bug, inconsistency, or wrong generator/MCP output
  2. Classify — USM tool itself (CLI commands, MCP tool behaviour, generator output, schema validation) vs this project (app code, infra, this repo's .usm specs)
  3. Branch — project scope → existing feedback policy; USM-tool scope → upstream routing

Route a USM tool bug upstream (route-upstream) ​

USM tool bugs are drafted and filed against the upstream tracker with version and environment context.

  1. Read — upstream tracker URL — feedback.upstream_tracker, default https://github.com/Smith-Gray-Pty-Ltd/usm/issues
  2. Draft — issue with: @smithgray/usm version, command/tool invoked, repro, expected vs actual
  3. Respect-policy — human-gate: ask the human before filing; direct-to-github: gh issue create -R Smith-Gray-Pty-Ltd/usm
  4. Forbidden — never file USM tool bugs in the consuming project's tracker or .usm/feedback

Render the scope-aware protocol everywhere (render-scope-aware-protocol) ​

The Where does the bug live? guidance is emitted into every agent-facing surface from one code path.

  1. Generate — generateFeedbackProtocol gains a scope table: project scope vs USM tool scope with respective destinations
  2. Render — all rules files (AGENTS.md, CLAUDE.md, .cursor/rules/usm.mdc, copilot, opencode skill) via the shared block
  3. Render — docs feedback page (generateFeedbackPage) gains the same scope table

MCP tool carries the distinction (mcp-tool-explicit) ​

usm_report_feedback surfaces the scope question at the tool boundary.

  1. Update — tool description: distinguishes project feedback from USM tool bugs; names the upstream repo
  2. Update — human-gate draft response: if the entry looks like a USM tool bug, suggests routing upstream instead

Guarantees ​

scope-branch-explicit ​

Every generated feedback protocol explicitly branches on bug scope before stating where it goes

Acceptance criteria:

  • [ ] A 'Where does the bug live?' distinction rendered in every rules file
  • [ ] Project scope: existing policy behaviour unchanged
  • [ ] USM-tool scope: upstream URL named literally with the gh -R command

upstream-default-and-override ​

The upstream tracker has a default and a system.feedback override

Acceptance criteria:

no-misfiling ​

The protocol must forbid filing USM tool bugs against the consuming project

Acceptance criteria:

  • [ ] Explicit 'never file USM tool bugs in this repo's tracker' rule
  • [ ] usm_report_feedback human-gate draft mentions upstream routing for tool bugs

one-source-many-surfaces ​

Scope routing text is generated from a single code path into all surfaces

Acceptance criteria:

  • [ ] rulesFiles.ts generateFeedbackProtocol is the single source
  • [ ] Docs feedback page and MCP tool text stay consistent with it

Test specifications ​

protocol-renders-both-scopes ​

Given:

  • system_usm_with_feedback_block: true
  • run_generate: true

Then:

  • assertion: generated AGENTS.md contains the scope distinction
  • assertion: upstream URL literal present
  • assertion: project-scope behaviour unchanged from prior policy text

upstream-override-honoured ​

Given:

Then:

  • assertion: generated protocol uses the override URL

mcp-description-explicit ​

Given:

  • read_mcp_tool_registration: true

Then:

  • assertion: usm_report_feedback description distinguishes project vs USM tool bugs
  • assertion: upstream repo named in the description

schema-accepts-override ​

Given:

  • system_usm_with_upstream_tracker: true

Then:

  • assertion: usm validate passes
  • assertion: absent field still validates (optional)

Implementation ​

  • Primary: src/generators/rulesFiles.ts
  • Test code: tests/opencodeFeedback.test.ts
  • Test code status: manual

See Also ​

  • usm/agent-feedback
  • usm/gen-rules-files
  • usm/opencode-integration