📦 deps(thirdparty): update snapshots

2026-06-02 16:01:55 +00:00
parent 8696cd9e52
commit ac7fffe532
834 changed files with 153251 additions and 1426 deletions
@@ -0,0 +1,54 @@
+# Command Reference
+
+`user-thoughts` accepts `/user-thoughts` and `/ustht`. They are equivalent.
+
+## Command Summary
+
+| Command | Meaning |
+|---|---|
+| `/ustht init` | Initialize `.ustht/` in the current project. |
+| `/ustht status` | Show skill state, instant state, raw count, and dimension count. |
+| `/ustht skill` | Show `SKILL_STATUS`. |
+| `/ustht skill on|off` | Enable or disable write operations. |
+| `/ustht instant` | Show `INSTANT_STATUS`. |
+| `/ustht instant on|off` | Enable or disable instant capture. |
+| `/ustht sortin [--dry]` | Append raw entries into mdbase. |
+| `/ustht resort [--dry]` | Reorganize all mdbase content semantically. |
+| `/ustht raw` | Show unprocessed raw entries. |
+| `/ustht mdbase show [--all|--dimension]` | Show the index, all dimensions, or one dimension. |
+| `/ustht mdbase export [--all|--dimension]` | Export mdbase content. |
+| `/ustht import <path>` | Import project-relevant decisions from markdown files. |
+| `/ustht ignore start|end` | Start or stop a temporary ignore interval. |
+| `/ustht ignore --last` | Remove the last raw entry and record it as ignored. |
+| `/ustht ignore show` | Show ignored entries. |
+
+## Natural-Language Mapping
+
+Agents may map clear user intent to commands:
+
+- "turn on project memory" -> `/ustht skill on && instant on`
+- "stop recording this" -> `/ustht ignore start`
+- "start recording again" -> `/ustht ignore end`
+- "organize what I said" -> `/ustht sortin`
+- "show what you remember" -> `/ustht mdbase show`
+- "ignore the last note" -> `/ustht ignore --last`
+
+When intent is ambiguous, ask a short clarification instead of guessing.
+
+## Chained Commands
+
+Commands can be chained with `&&` and should run left to right. Stop only if a command fails in a way that makes the following command unsafe.
+
+Example:
+
+```text
+/ustht skill on && instant on && status
+```
+
+## Dimension Arguments
+
+Dimension names must pass validation:
+
+- lowercase letters, digits, and hyphens;
+- `/` allowed for subdirectories, such as `ui/outline`;
+- no spaces, `..`, backslashes, absolute paths, or reserved names.
@@ -0,0 +1,84 @@
+# Edge Cases
+
+Use these examples to keep behavior predictable.
+
+## No Runtime Directory
+
+User: `/ustht status`
+
+Agent: `.ustht/ was not found. Run /ustht init first.`
+
+## Skill Disabled
+
+If `SKILL_STATUS=off`, write commands should not modify files. Read commands such as `status`, `raw`, and `mdbase show` may still run.
+
+## Instant Mode Disabled
+
+When `INSTANT_STATUS=off`, do not capture natural-language thoughts automatically. Explicit commands still run.
+
+## Command Plus Thought
+
+User: `Make buttons use 8px radius, and /ustht status`
+
+Agent: run the command and record the UI preference if instant capture is enabled. Do not record the command text itself.
+
+## Message Suffix Ignore
+
+User: `This color experiment is temporary /ustht ignore`
+
+Agent: do not write it to raw. Record it in `ignored/` as a suffix-ignored entry if ignore tracking is available.
+
+## Ignore Interval
+
+User: `/ustht ignore start`
+
+Agent: enter ignore mode for the current context.
+
+User: `Try three throwaway layouts.`
+
+Agent: do not record the thought.
+
+User: `/ustht ignore end`
+
+Agent: exit ignore mode.
+
+## Last Entry Ignore
+
+User: `/ustht ignore --last`
+
+Agent: remove the last unprocessed raw entry and append it to `ignored/`. If no entry exists, say so without failing.
+
+## Processed Marker Mentioned by User
+
+User: `Maybe we should use <!-- processed --> as a completion marker in docs.`
+
+Agent: preserve that text as ordinary user content. `sortin` checks only the first line of raw files.
+
+## Illegal Dimension Names
+
+Reject dimensions containing spaces, `..`, backslashes, absolute paths, or unsafe characters.
+
+Examples:
+
+- Reject `../../../etc/passwd`.
+- Reject `my file`.
+- Accept `ui/details`.
+- Accept `dev-stack`.
+
+## Chained Commands
+
+User: `/ustht skill on && instant on && status`
+
+Agent: run commands left to right and report a compact summary.
+
+## Import With No Relevant Content
+
+If `/ustht import README.md` finds no project decisions, report that no entries were extracted and do not write empty dimension sections.
+
+## Multi-Agent Writes
+
+No file locks are provided. If multiple agents are active, coordinate before `sortin` or `resort` to avoid conflicting writes.
+
+## Sensitive Content
+
+If the user says a thought contains secrets or personal data, prefer ignore behavior and remind them that `.ustht/` is not automatically redacted.
@@ -0,0 +1,65 @@
+# Safety and Data Integrity
+
+This document defines path safety, input validation, and data-integrity rules for `user-thoughts`.
+
+## Path Safety
+
+All runtime file operations must stay inside `#ustht/` unless an import command reads project-local markdown files.
+
+Dimension names are used to construct paths, so validate them strictly:
+
+| Rule | Reason |
+|---|---|
+| Each path segment uses `[a-z0-9-]` only | Prevents shell and path surprises. |
+| Each segment starts and ends with `[a-z0-9]` | Avoids hidden or malformed files. |
+| `/` is allowed only as a dimension subdirectory separator | Supports `ui/outline`. |
+| `..`, backslashes, spaces, and absolute paths are forbidden | Prevents path traversal. |
+| Reserved names are forbidden | Avoids collisions with runtime folders. |
+
+Reserved names: `backlog`, `readme-ai`, `export`, `raw`, `ignored`, `define`, `general`.
+
+## Content Safety
+
+Raw entries use this format:
+
+```text
+- [HH:MM] original user text | suggested-dim:dimension
+```
+
+The suffix is agent-generated metadata. User text may contain markdown and should be preserved as written. Parse the last ` | suggested-dim:` separator only.
+
+`<!-- processed -->` is meaningful only as the first line of a raw file. If the user mentions that string inside a thought, treat it as normal content.
+
+## define.ini Safety
+
+Allowed keys and values:
+
+| Key | Allowed value |
+|---|---|
+| `SKILL_STATUS` | `on` or `off` |
+| `INSTANT_STATUS` | `on` or `off` |
+| `LAST_SORTIN` | empty or `yyyy-mm-dd HH:MM` |
+
+Values must not contain newlines or `=`. Write the whole file rather than appending partial fragments.
+
+## Shell Safety
+
+- Do not execute user-provided shell commands.
+- Do not use `eval` or dynamic execution.
+- Construct file paths only from validated dimensions or fixed template paths.
+- During initialization, copy known template files safely instead of recursively shell-copying arbitrary directories.
+
+## Data Integrity
+
+`sortin` is not fully atomic. To reduce partial-write risk:
+
+1. Parse raw entries first.
+2. Write dimension files.
+3. Mark raw files as processed only after writes succeed.
+4. Update `LAST_SORTIN` last.
+
+Processed raw files are retained for traceability. Dimension files should be appended or marked deprecated; do not silently delete user history.
+
+## Sensitive Data
+
+The skill preserves original wording and does not redact secrets or personal data. Users should use ignore commands before sensitive content is captured, and teams should protect `.ustht/` with normal repository and filesystem hygiene.
@@ -0,0 +1,76 @@
+# Sortin and Resort Algorithms
+
+This document describes how raw thoughts become organized mdbase records.
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `/ustht sortin` | Soft maintenance: append new raw entries into mdbase without restructuring existing content. |
+| `/ustht resort` | Hard maintenance: review all mdbase content, deduplicate, reclassify, merge, and update indexes. |
+| `--dry` | Preview intended changes without writing. |
+
+## Raw Format
+
+Before processing:
+
+```text
+- [14:30] Make buttons use 8px radius | suggested-dim:ui/details
+- [14:45] Login should use a dark theme | suggested-dim:ui/outline
+- [15:10] Use REST APIs, not GraphQL | suggested-dim:dev-stack
+```
+
+After processing, the first line of the file becomes:
+
+```text
+<!-- processed -->
+```
+
+## Soft Append Format
+
+A raw entry is appended under a date heading in the selected dimension file:
+
+```markdown
+## 2026-06-01
+
+- Make buttons use 8px radius
+```
+
+Rules:
+
+- Preserve original wording.
+- Remove only the timestamp and `suggested-dim` suffix.
+- Group entries by raw-file date.
+- Append to an existing date section when present.
+- Create a new date section when needed.
+
+## Dimension Management
+
+Create a new dimension only when the thought does not fit an existing dimension. Dimension names must be kebab-case path segments and must pass safety validation.
+
+When `resort` finds overlapping dimensions, merge them into the clearest target and preserve provenance. When a dimension is no longer useful, mark it with `<!-- deprecated -->` instead of deleting it.
+
+## Classification Priority
+
+1. User-specified dimension.
+2. Exact existing dimension match.
+3. Closest semantic existing dimension, with a note if the fit is weak.
+4. `general.md` fallback.
+
+## Import Algorithm
+
+`/ustht import <path>` scans markdown files under a safe project-local path and extracts project-relevant user decisions, constraints, and requirements. It should not modify source files. Imported entries should include source provenance such as `[source:docs/design.md]`.
+
+Skip ordinary technical docs, generated docs, API reference text, and code comments unless they clearly encode a user decision.
+
+## Summary Output
+
+After `sortin`, report the number of processed entries and destination dimensions, for example:
+
+```text
+Soft maintenance complete. Processed 3 thoughts:
+  -> ui/details.md: +1
+  -> ui/outline.md: +1
+  -> dev-stack.md: +1
+LAST_SORTIN updated to 2026-06-01 15:30
+```