ur-agent 1.68.18 → 1.69.0

package/technical/07-memory-and-context.md

@@ -1,175 +0,0 @@
-# 07 — Memory & Context Management
-
-Source of truth: `src/memdir/`, `src/services/{SessionMemory,extractMemories,compact,contextCollapse}/`,
-`src/commands/{memory,remember,forget,memory-retention,semantic-memory,knowledge,context-pack,compact,context}`.
-
-## Layered memory model
-
-| Layer | Location | Written by | Loaded |
-|---|---|---|---|
-| Project instructions | `UR.md` (repo root, committed) | user or `/init` | normal, non-`--bare` root sessions |
-| Local project instructions | `UR.local.md` (gitignored) | user | normal, non-`--bare` root sessions |
-| Auto-memory (memdir) | the project-scoped auto-memory path under `~/.ur` (`autoMemoryDirectory` setting; `UR_CODE_REMOTE_MEMORY_DIR` in containers) | the main agent, while working, when the injected memory instructions call for a durable note | either the bounded `MEMORY.md` index or selected topic attachments, depending on the relevance-recall gate |
-| Team memory | shared team paths (`teamMemPaths.ts`, `TEAMMEM` build gate) | team sync service | source-only in this repository's standard npm build |
-| Session transcripts | `~/.ur/projects/<slug>/` | automatic | via `/resume`, past-session search |
-
-### Auto-memory (memdir)
-- On by default; disable via `UR_CODE_DISABLE_AUTO_MEMORY=1`, `--bare`, or
-  `autoMemoryEnabled: false` (project-level opt-out supported).
-- The stable path loads the byte/line-capped `MEMORY.md` index. When the
-  `tengu_moth_copse` runtime gate is enabled, UR instead performs a
-  non-blocking recall: a lexical header prefilter narrows candidates, a small
-  model selects at most three, and each selected file is truncated and
-  session-byte-capped before attachment. A failed or late selector never blocks
-  the main turn.
-- Topic files use frontmatter (`name`, `description`,
-  `type: user|feedback|project|reference`); `MEMORY.md` is their index.
-- The normal npm build asks the main agent to maintain these files directly.
-  The separate turn-end `extractMemories` implementation is behind the
-  compile-time `EXTRACT_MEMORIES` feature and is not bundled by
-  `scripts/bundle.mjs`; setting an environment variable alone cannot enable
-  that background extractor.
-- `/memory` opens memory files for editing. There is no special `#` prompt
-  prefix for writing a note.
-- `/remember <text>` writes the legacy project note and also promotes the note
-  into auto-memory when enabled. `/forget <text>` removes matching legacy
-  notes, their deterministic promoted topic files, and the corresponding index
-  links. Persistence failures are reported as failures or partial results,
-  rather than as successful saves. The project-note JSONL text is non-empty
-  and capped at 64 KiB; its `.ur/memory/` path must remain a regular directory
-  inside the canonical workspace, and symlinked collection files are rejected.
-
-### Explicit memory commands
-```
-/remember we never bump major versions on Fridays   # save a fact
-/forget Fridays                                     # remove matching notes
-/memory                                             # edit files interactively
-/memory-retention set --ttl-days 90 --max-entries 500 --decay-days 14
-/memory-retention prune                             # apply the policy now
-```
-The bundled `/remember` skill (no args) reviews auto-memory and proposes promotions to
-UR.md / UR.local.md and detects stale/duplicate/conflicting entries.
-
-### Automatic learning
-- On by default; disable via `UR_CODE_DISABLE_AUTO_LEARNING=1` or
-  `automaticLearningEnabled: false`.
-- ci-loop, arena, escalation, test-first, and cloud-task outcomes are folded into
-  `.ur/learning/stats.json` as local JSON. This automatic path uses no model
-  calls and no prompt tokens.
-- Learned success rates bias auto model routing and escalation only when there
-  is enough evidence; otherwise static routing is unchanged.
-
-### Lexical memory index
-```
-/semantic-memory build            # build a local lexical index
-/semantic-memory search "how do we rotate tokens"
-/semantic-memory status
-```
-
-Despite the historical command name, this implementation does not call an
-embedding model. It tokenizes paragraphs from `UR.md`, `README.md`,
-`.ur/memory/`, and `.ur/docs/`, then ranks by query-token overlap. Use
-`/knowledge build --embeddings` or `/code-index build` when dense embedding
-retrieval is required.
-
-### Knowledge base (`/knowledge`, alias `/kb`) — curated, with provenance
-```
-/knowledge add src/auth/jwt.ts --note "token flow" --label auth
-/knowledge build --embeddings --embed-model nomic-embed-text
-/knowledge search "refresh rotation"
-/knowledge prune --older-than 60
-/knowledge status
-```
-
-### Context pack (`/context-pack`, aliases `/ctx-pack`, `/project-manifest`)
-Repo-architecture summary + task memory + compressed project context in `.ur/context/`:
-```
-/context-pack scan
-/context-pack remember --type decision --text "we chose fastify over express"
-/context-pack memory verify
-/context-pack memory quarantine
-/context-pack memory rollback --to <entry-id>
-/context-pack compress
-/context-pack status
-```
-Types: `decision | constraint | command | diff | note | architecture |
-preference | attempt | accepted | rejected`. New entries contain UUIDs,
-source provenance, content digests, and a SHA-256 previous-entry chain. Appends
-are locked, private, no-follow, and fsynced; reads fail closed. Quarantine and
-rollback preserve a private copy of the full original before replacement.
-
-## Context window management
-
-| Feature | How |
-|---|---|
-| Visualize usage | `/context` (colored grid); `/files` is an ant-only command and is absent from the standard npm CLI |
-| Manual compaction | `/compact [focus instructions]` |
-| Auto-compaction | `src/services/compact` — triggers at one canonical model-aware threshold; `DISABLE_AUTO_COMPACT` env disables; PreCompact/PostCompact hooks fire |
-| Context collapse | `src/services/contextCollapse` and `CtxInspect` are behind the compile-time `CONTEXT_COLLAPSE` feature, which the standard npm bundle does not include |
-| Micro-compaction | session-memory compact (`sessionMemoryCompact.ts`): force on with `ENABLE_UR_CODE_SM_COMPACT=1`, force off with `DISABLE_UR_CODE_SM_COMPACT=1`; otherwise both `tengu_session_memory` and `tengu_sm_compact` runtime gates must be on |
-| Clear | `/clear` (aliases `/reset`, `/new`) |
-| Read caps | Read tool truncates large files/lines; `/read`, `/analyze`, `/summarize` for deliberate loads |
-
-The effective context window always stays positive, including for small local
-models. By default proactive compaction reserves a scaled output buffer (up to
-20,000 tokens) plus a 13,000-token compact/manual safety band. The global
-`compaction.autoThreshold` setting can instead select 50–95% of the effective
-window while retaining a 3,000-token manual reserve;
-`UR_AUTOCOMPACT_PCT_OVERRIDE` is the explicit environment override. Trigger
-logic, prompt notifications, `/context`, and the SDK all use this same
-threshold and estimated live usage, including messages added after the last
-provider response.
-
-When proactive auto-compaction is active, the prompt notification and
-`/context` show a clamped approximate 0–100% value remaining until the actual
-trigger, with separate warning and final-error bands. The estimate uses the
-same live token counter, while the query may conservatively improve it by
-snipping or pruning immediately before the trigger. Reactive-compaction and
-context-collapse modes own their thresholds and therefore do not display a
-misleading proactive countdown. A successful compaction suppresses the stale
-pre-compact warning.
-
-Full, partial, and session-memory compaction restore the authoritative live
-task state after the boundary. Task V2 snapshots retain exact IDs, statuses,
-owners, and dependency edges; legacy TodoWrite snapshots retain order and
-status. The snapshot is bounded to 64 actionable-first records and an
-estimated 6,000-token budget. If more exist, the model is required to call
-`TaskList` before task mutation rather than guessing omitted IDs. Compact
-boundaries also permanently consume the task-gate's initial trivial-call
-allowance so compaction cannot reopen an implementation bypass.
-
-## Repo wiki & map
-
-```
-/wiki generate       # .ur/wiki/: overview, architecture, dependency map (from DNA + code index)
-/wiki install-hook   # refresh automatically after every merge
-/wiki map            # regenerate .ur/repo-map.md
-```
-When `.ur/repo-map.md` exists and is fresh (less than seven days), a byte-capped
-repo map is injected into the system prompt automatically (zero tokens until
-generated).
-
-## Project DNA & indexes
-
-```
-/dna              # detect language, package manager, build/test/lint → .ur/dna
-/index            # build workspace file index (.ur/index)
-/code-index build # semantic embeddings index — CodeSearch auto-enables once built
-/code-index watch # keep it fresh
-/code-index search "debounce input"
-```
-`/project` and `/workspace` display the recorded DNA + workspace facts.
-
-## What gets injected into the system prompt
-
-The interactive and print entrypoints both assemble the prompt through
-`src/constants/prompts.ts` plus the context helpers. A normal root prompt
-includes UR.md/UR.local.md instructions, auto-memory as described above, the
-active working-mode discipline, output style, enabled-tool guidance, and
-environment information. Read-only `Explore` and `Plan` subagents omit the
-UR.md hierarchy when the default-on `tengu_slim_subagent_agentmd` runtime gate
-is active and the caller did not explicitly supply user context. Project DNA
-is not injected directly; it can appear through a fresh generated repo map.
-`--bare` replaces the root prompt with a minimal prompt and drops automatic
-memory, hooks, and most extras. The internal `--dump-system-prompt` diagnostic
-exists only in ant builds.

package/technical/08-skills-plugins-workflows.md

@@ -1,211 +0,0 @@
-# 08 — Skills, Plugins & Workflows
-
-Source of truth: `src/skills/`, `src/utils/plugins/`, `src/plugins/`,
-`src/services/agents/{workflows,patterns}.ts`, `src/tools/WorkflowTool/`.
-
-## Skills
-
-Two skill formats coexist:
-
-### 1. Prompt skills (SKILL.md)
-Directory format `skill-name/SKILL.md` with Agent Skills-compatible YAML
-frontmatter (`name`, `description`, optional `license`, `compatibility`,
-`metadata`, `allowed-tools`). Loaded from:
-- project: `.ur/skills/<name>/SKILL.md`
-- user: `~/.ur/skills/<name>/SKILL.md`
-- cross-client project/user: `.agents/skills/<name>/SKILL.md` and
-  `~/.agents/skills/<name>/SKILL.md`
-- plugins and MCP servers (MCP skills never execute embedded shell blocks)
-- bundled skills compiled into the binary (`src/skills/bundled/`, list in doc 03 §13)
-
-Resolution is deterministic: nearer project roots beat parent roots, project
-beats user, and native `.ur` beats cross-client `.agents` at the same scope.
-
-Body supports `${UR_SKILL_DIR}` (skill directory path) and `${UR_SESSION_ID}`
-substitution, plus the exclamation-backtick inline form and
-exclamation-labelled fenced shell blocks for any loaded non-MCP prompt skill.
-Those commands still pass through the normal
-shell-tool permission checks and the skill's `allowed-tools` rules. Remote MCP
-skills never execute embedded shell; “local” here is not a cryptographic trust
-claim.
-
-```
-/create-skill release-notes "draft release notes from git log" --project
-# → .ur/skills/release-notes/SKILL.md, then invoke with:
-/release-notes v2.1
-```
-`/skills` opens the prompt-skill browser; the model can also self-invoke prompt
-skills through the `Skill` tool. `/skill` is intentionally separate and runs
-the executable `skill.yaml` workflows below. Neither slash token aliases the
-other.
-`/skillify` (bundled) converts the current session's workflow into a skill.
-
-For a file-backed `SKILL.md`, UR attempts to compute deterministic content-tree
-and permission digests and validates names, directory identity, field
-types/lengths, and metadata; signed skills cannot contain symlinks. Trust
-commands:
-
-```
-ur skill verify <name-or-directory> [--require-trusted] [--json]
-ur skill keygen <key-id> [--out <private-key.pem>]
-ur skill sign <name-or-directory> --key <private-key.pem> --key-id <key-id>
-```
-
-Ed25519 manifests embed the public key and signed digests. Trusted keys live in
-a private store (override its file with `UR_SKILL_TRUSTED_KEYS_FILE`). In the
-default mode, provenance-inspection and Agent Skills validation failures are
-logged and an otherwise readable skill may still load.
-`UR_SKILLS_STRICT_SPEC=true` rejects invalid or uninspectable skills;
-`UR_SKILLS_REQUIRE_TRUSTED_SIGNATURE=true` requires a verified trusted
-signature at load. When provenance was successfully recorded, UR re-hashes the
-file tree immediately before invocation to detect changes after discovery.
-The corresponding `ur skill` trust flags are declared by the shipped CLI, not
-only by the local command parser.
-
-### 2. Executable skills (skill.yaml) — skills as workflows
-`skill.yaml` is searched through the same project/user native and cross-client
-skill roots (`.ur/skills` and `.agents/skills`).
-`src/skills/skillSpec.ts` compiles it into a `WorkflowSpec`:
-
-```yaml
-version: 1
-name: deploy-checklist
-description: Gate a deploy behind checks
-allowedTools: [Bash, Read]
-steps:
-  - id: tests
-    name: Run tests
-    agent: general-purpose
-    prompt: Run the full test suite and report failures.
-  - id: approve
-    name: Human sign-off
-    agent: general-purpose
-    prompt: Summarize risk.
-    dependsOn: [tests]
-    gate: approval
-    checkpoint: true
-```
-The directory may include `instructions.md`, `scripts/`, `templates/`, and
-`checklists/` referenced via `${UR_SKILL_DIR}`. `allowedTools` is validated,
-copied to every compiled workflow step, and passed to the child `ur -p` process
-as its exact `--tools` pool; it is not merely descriptive metadata. Each
-step's `agent` is also forwarded as `ur --agent <name>`, so the selected
-built-in or project-defined agent governs that child session.
-
-```
-/skill list · /skill show deploy-checklist · /skill run deploy-checklist
-/skill approve deploy-checklist approve
-/skill run deploy-checklist --resume · /skill reset deploy-checklist
-/skill init <name>
-```
-
-An approval-gated step is held before its model/tool execution. Approval is
-accepted only for the currently held step, stored as a single-use token, and
-consumed by `run --resume`. A run that fails, is blocked, or is held returns a
-nonzero command status.
-
-The `ur skill verify|sign|keygen` supply-chain commands above operate on
-Agent Skills directories containing `SKILL.md`. Executable `skill.yaml`
-workflows are parsed and schema-validated, but that execution path does not
-currently require or verify the `SKILL.md` Ed25519 manifest. Do not treat
-signing a neighboring prompt skill as a signature over `skill.yaml`.
-
-All skill, plugin, workflow, and built-in invocation tokens pass through the
-same registry normalizer. Earlier sources retain priority, duplicate canonical
-tokens are omitted, and a later command loses only aliases already claimed by
-another command.
-
-## Workflows (`/workflow`, aliases `/wf`, `/workflows`)
-
-Declarative, checkpointed DAGs of agent steps (`src/services/agents/workflows.ts`).
-Each step: `id`, `name`, `agent` (subagent type), `prompt`, `dependsOn`,
-optional `allowedTools`, `gate: approval|verification`,
-`verificationMode: enforcing|advisory`, and `checkpoint: true`. Stored under
-`.ur/workflows/`.
-
-```
-/workflow init release             # scaffold
-/workflow validate release        # cycle/agent checks
-/workflow graph release --ascii   # Mermaid or ASCII rendering
-/workflow plan release            # topological dry-run
-/workflow run release             # execute until completion, failure, or a gate hold
-/workflow approve release step-id # approve the currently held approval step
-/workflow run release --resume    # consume approval/resume persisted progress
-/workflow next release            # show the next ready step
-/workflow done release step-id    # manually complete an ungated step only
-/workflow reset release
-```
-
-Progress and exact step outputs are persisted after every completed step for
-crash recovery, within a 32 KiB per-step and 256 KiB per-run output budget.
-Oversized outputs are not silently truncated: the completed step remains done
-and is never replayed, while an output-dependent successor fails closed on
-resume and tells the operator to reset for an intentional rerun. Legacy state
-without captured outputs follows the same rule. Resumed completed steps are
-reported as done with zero executions in the resumed run, not as skipped.
-`checkpoint: true` additionally creates a semantic checkpoint record.
-Parallel waves use all-settled accounting: if one branch fails, every sibling
-that already ran is still recorded and successful siblings remain completed;
-only dependent, unstarted steps are reported as skipped.
-Verification gates require exactly one standalone non-error `VERDICT: PASS`
-line; inline, missing, or multiple verdicts, `FAIL`, `PARTIAL`, and runner
-errors fail closed unless that step explicitly
-sets `verificationMode: advisory`. Non-completed CLI runs return nonzero.
-The declared `agent` is passed to each child session through `--agent`; the
-built-in `worker` alias falls back to `general-purpose`, while a project
-definition named `worker` takes precedence.
-Workflow execution is foreground in this build. Historical
-`LocalWorkflowTask` records remain renderable, but no runtime constructor or
-stop operation advertises them as live background tasks.
-
-## Collaboration patterns (`/pattern`)
-
-Prebuilt multi-agent topologies (`src/services/agents/patterns.ts`):
-`peer` (plan-execute-express-review), `doe` (data-oriented ensemble), `concurrent`,
-`handoff`, `debate`, `parallel`.
-
-```
-/pattern list
-/pattern show peer
-/pattern run debate "adopt tRPC or keep REST?" --execute
-/pattern install peer --save     # materialize as an editable workflow
-```
-
-## Plugins
-
-Plugin manifests + marketplaces (`src/utils/plugins/`, `.ur-plugin/marketplace.json`
-format). Plugins can contribute: commands, skills, agents, hooks, MCP servers, output
-styles.
-
-```
-ur plugin marketplace add github.com/acme/ur-plugins   # or a local path
-ur plugin marketplace list / update / remove <name>
-ur plugin install fmt@acme -s project     # scopes: user | project | local
-ur plugin list --json --available
-ur plugin enable fmt / disable fmt / disable -a
-ur plugin update fmt
-ur plugin validate ./my-plugin            # manifest validation
-ur plugin doctor --path ./plugins         # diagnose
-/plugin                                    # interactive Ink UI (alias /plugins, /marketplace)
-/reload-plugins                            # activate pending changes in-session
-ur --plugin-dir ./dev-plugin               # session-only plugin load
-```
-Settings: `enabledPlugins`, `pluginConfigs`, `extraKnownMarketplaces`,
-`strictKnownMarketplaces`, `blockedMarketplaces`, `strictPluginOnlyCustomization`.
-
-## Local helper tools (`/toolsmith`)
-
-Scaffolds a small custom tool under `.ur/tools/<name>/` in python/bash/node/go/rust; UR
-runs it with approval like any command:
-```
-/toolsmith csv-differ python
-```
-
-## Automations (`/automation`)
-
-Project-local scheduled prompts (`.ur/automations/`), separate from skills:
-```
-/automation create nightly-tests --schedule "0 3 * * *" --prompt "run tests; open an issue on failure"
-/automation run-due                      # execute anything due now
-ur automation install --platform launchd --interval 300   # host scheduler integration
-```