Mikael Hugo a611cd5792 feat: introduce repo-vcs skill and add JSDoc annotations across core modules

- Add repository-vcs-context.ts to detect and inject VCS context (Git/Jujutsu)
  into the agent system prompt; wire in repo-vcs bundled skill trigger
- Add src/resources/skills/repo-vcs/ skill for commit, push, and safe-push workflows
- Add JSDoc Purpose/Consumer annotations to app-paths, bundled-extension-paths,
  errors, extension-discovery, extension-registry, headless-types, headless, and traces
- Add justfile and just to flake.nix devShell
- Fill out new-user-onboarding.md spec (Draft) and core-beliefs.md (Status: Accepted)
- Add notification-event-model.md design doc and notification-source-hygiene.md spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-01 21:36:32 +02:00

2.8 KiB

Raw Blame History

Notification Source Hygiene

Status: Draft

User Problem

Users can lose trust when automated workflow or system notifications appear to be messages they typed, or when repeated notifications interrupt the latest real user request.

Observed facts:

The current working CLI/product is Singularity Forge.
singularity-foundry is the old name/path.
The issue report used "SF" as shorthand for workflow notifications.
The source implementation for notification and steering behavior lives in /home/mhugo/code/singularity-forge.

Inferred facts:

The Forge/Foundry naming mismatch can make triage confusing, but it is not the runtime bug.
The bug class is automated event source confusion: notices need to be handled separately from user-authored messages.

Goals

Separate user-authored messages from automated workflow, system, and tool notifications.
Keep the latest real user request visible as the primary interaction.
Group duplicate automated notices when they repeat without adding new actionable information.
Preserve enough metadata to debug notification incidents.

Non-Goals

Do not suppress security, permission, or destructive-action warnings.
Do not hide tool failures that block the requested work.
Do not implement notification routing until the owning runtime or integration exists.

Behavior

A future implementation should treat each inbound event as one of:

user_message: content intentionally submitted by the user.
system_notice: platform or workflow status that should be labeled and visually separated.
tool_notice: command, tool, or automation status.
blocking_notice: notice that requires user action before work can continue.

Repeated non-blocking notices with the same source and equivalent content should be collapsed into a single visible event with a count and time range. Blocking notices must remain visible, but they should still be labeled as notices rather than user input.

Failure States

Automated notifications are rendered as if the user typed them.
Duplicate notices push the current user request out of view.
A non-blocking notice prevents tools or responses from processing the real user message.
A blocking notice is hidden or collapsed in a way that prevents informed consent.

Acceptance Criteria

The UI or transcript clearly distinguishes user messages from automated notices.
Duplicate non-blocking notices are grouped without losing source and timestamp metadata.
A regression test or product eval proves that automated notices do not supersede the latest real user message.
Blocking notices still interrupt when user consent or safety requires it.

Verification

To be replaced with concrete commands when the owning implementation exists:

# notification routing unit test
# transcript rendering regression test
# product eval for duplicate automated workflow notices

2.8 KiB Raw Blame History