📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,236 @@
|
||||
---
|
||||
name: user-thoughts
|
||||
description: >-
|
||||
Persist user decisions and project constraints to mdbase across sessions.
|
||||
Trigger on /user-thoughts or /ustht, or when the user discusses architecture,
|
||||
tech stack, rules, UI/UX, or project memory.
|
||||
license: MIT
|
||||
source: "https://github.com/JularDepick/user-thoughts.SKILL"
|
||||
source_repo: JularDepick/user-thoughts.SKILL
|
||||
source_type: community
|
||||
date_added: "2026-05-31"
|
||||
author: JularDepick
|
||||
tags: [userthoughts, documentation, project-management, mdbase]
|
||||
tools: [claude, cursor, gemini]
|
||||
risk: safe
|
||||
allowed-tools: read write bash
|
||||
metadata:
|
||||
author: JularDepick
|
||||
category: productivity
|
||||
supported_agents: "[claude, cursor, gemini]"
|
||||
---
|
||||
|
||||
# user-thoughts.SKILL
|
||||
|
||||
## Overview
|
||||
|
||||
Across sessions and across agents, project decisions and user constraints are easy to lose. `user-thoughts` persists those decisions into a project-local `mdbase` so any future agent can recover the user's intent without re-deriving it from scratch.
|
||||
|
||||
The skill records user intent. It does not replace normal task execution. If the user says, "make the button red," the agent should both make the change and record the preference when persistent project memory is useful.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when the user states or revises:
|
||||
|
||||
- Project rules, constraints, preferences, or requirements.
|
||||
- Architecture, tech-stack, data-model, deployment, or workflow decisions.
|
||||
- UI/UX direction, copy standards, visual preferences, or design rationale.
|
||||
- Backlog items, planned work, rejected options, or decisions that future agents should inherit.
|
||||
- A direct command beginning with `/user-thoughts` or `/ustht`.
|
||||
|
||||
Do not use it for unrelated small talk, transient chatter, or content the user explicitly asks to ignore.
|
||||
|
||||
## Language Policy
|
||||
|
||||
- All bundled skill files, scripts, templates, and reference docs are written in English.
|
||||
- Agent-facing command output should follow the user's current conversation language when the agent can reasonably do so.
|
||||
- Raw user thoughts should preserve the user's original wording. Do not translate, summarize, or clean the user's intent unless the user asks for that.
|
||||
|
||||
## Core Workflow
|
||||
|
||||
```text
|
||||
User message -> Agent identifies persistent project intent -> write to #raw/
|
||||
-> /ustht sortin groups raw entries into #mdbase/
|
||||
-> /ustht mdbase show exposes the organized memory base
|
||||
```
|
||||
|
||||
## Runtime Modes
|
||||
|
||||
- Passive mode: `INSTANT_STATUS=off`; only explicit skill commands run.
|
||||
- Instant mode: `INSTANT_STATUS=on` and `SKILL_STATUS=on`; project-relevant user thoughts are written to `#raw/` as they appear.
|
||||
- Ignore mode: `ignore start` and `ignore end` mark a temporary interval that should not be recorded.
|
||||
- Read-only mode: if required read/write/bash tools are unavailable, show commands can still work but write commands should explain that the environment cannot persist data.
|
||||
|
||||
`SKILL_STATUS=off` pauses instant capture even when `INSTANT_STATUS=on`. Ignore intervals are context-local and do not persist across sessions.
|
||||
|
||||
## Path Definitions
|
||||
|
||||
- `@/`: the installed `user-thoughts/` skill directory.
|
||||
- `~/`: the current project working directory.
|
||||
- `#ustht/`: `~/.ustht/`.
|
||||
- `#mdbase/`: `~/.ustht/mdbase/`.
|
||||
- `#ignored/`: `~/.ustht/ignored/`.
|
||||
- `#raw/`: `~/.ustht/raw/`.
|
||||
- `#export/`: `~/.ustht/export/`.
|
||||
|
||||
## Runtime Directory Layout
|
||||
|
||||
```text
|
||||
.ustht/
|
||||
├── define.ini
|
||||
├── README.ai.md
|
||||
├── raw/
|
||||
│ └── yyyy-mm-dd.md
|
||||
├── ignored/
|
||||
│ └── yyyy-mm-dd.md
|
||||
├── mdbase/
|
||||
│ ├── backlog.md
|
||||
│ ├── README.ai.md
|
||||
│ └── details/
|
||||
│ ├── rules.md
|
||||
│ ├── plans.md
|
||||
│ ├── ui/
|
||||
│ │ ├── outline.md
|
||||
│ │ └── details.md
|
||||
│ ├── dev-stack.md
|
||||
│ └── general.md
|
||||
└── export/
|
||||
```
|
||||
|
||||
## Tools and Environment
|
||||
|
||||
Required tools:
|
||||
|
||||
- read/write: read and update files under `#ustht/`.
|
||||
- bash: create directories and run bundled scripts.
|
||||
|
||||
Optional tool:
|
||||
|
||||
- SubAgent: when available, use it for semantic `sortin` or `resort` maintenance that spans many files. Use the main agent directly only when subagents are unavailable.
|
||||
|
||||
## Bundled Scripts
|
||||
|
||||
The `scripts/` directory provides small Python helpers for mechanical operations:
|
||||
|
||||
| Script | Purpose | Example |
|
||||
|---|---|---|
|
||||
| `common.py` | Shared helpers | Imported by other scripts |
|
||||
| `status.py` | Show current runtime state | `python @/scripts/status.py` |
|
||||
| `init.py` | Initialize `.ustht/` | `python @/scripts/init.py` |
|
||||
| `show_raw.py` | Show unprocessed raw entries | `python @/scripts/show_raw.py` |
|
||||
| `show_mdbase.py` | Show mdbase index or a dimension | `python @/scripts/show_mdbase.py show --all` |
|
||||
| `sortin.py` | Soft-maintain raw entries into mdbase | `python @/scripts/sortin.py --dry` |
|
||||
| `write_raw.py` | Append one raw thought | `python @/scripts/write_raw.py "Use REST APIs" --dim dev-stack` |
|
||||
| `toggle.py` | Toggle skill or instant mode | `python @/scripts/toggle.py instant on` |
|
||||
| `ignore_ops.py` | Manage ignored entries | `python @/scripts/ignore_ops.py show` |
|
||||
|
||||
`resort` has no standalone script because it requires semantic review, deduplication, and restructuring by an agent.
|
||||
|
||||
## define.ini
|
||||
|
||||
`define.ini` stores simple key/value runtime state:
|
||||
|
||||
| Key | Value | Meaning |
|
||||
|---|---|---|
|
||||
| `SKILL_STATUS` | `on` or `off` | Whether the skill accepts write operations |
|
||||
| `INSTANT_STATUS` | `on` or `off` | Whether instant capture is enabled |
|
||||
| `LAST_SORTIN` | `yyyy-mm-dd HH:MM` or empty | Last soft-maintenance time |
|
||||
|
||||
Write the file atomically by replacing its complete contents. Do not append partial key/value fragments.
|
||||
|
||||
## Commands
|
||||
|
||||
Commands may use either `/user-thoughts` or `/ustht`.
|
||||
|
||||
### Status and Toggles
|
||||
|
||||
- `/ustht init`: create `.ustht/` and copy templates.
|
||||
- `/ustht status`: show status, raw counts, and dimension counts.
|
||||
- `/ustht skill`: show skill status.
|
||||
- `/ustht skill on|off`: enable or disable writes.
|
||||
- `/ustht instant`: show instant-capture status.
|
||||
- `/ustht instant on|off`: enable or disable instant capture.
|
||||
|
||||
### Maintenance
|
||||
|
||||
- `/ustht sortin [--dry]`: append unprocessed raw entries into mdbase.
|
||||
- `/ustht resort [--dry]`: semantically review and reorganize all mdbase content.
|
||||
|
||||
### Ignore Management
|
||||
|
||||
- `/ustht ignore start|end`: start or end an ignore interval.
|
||||
- `/ustht ignore --last`: remove the last raw entry and record it in `#ignored/`.
|
||||
- `/ustht ignore`: same as `--last` when used as a standalone command.
|
||||
- `/ustht ignore show`: list ignored entries.
|
||||
- Any message ending in `/ustht ignore` or `/user-thoughts ignore`: ignore that message.
|
||||
|
||||
### Content Review and Export
|
||||
|
||||
- `/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 to `#export/`.
|
||||
- `/ustht import <path>`: scan markdown files under a safe project-local path and merge project-relevant decisions into mdbase.
|
||||
|
||||
Chain commands with `&&`, for example `/ustht skill on && instant on`.
|
||||
|
||||
## Instant Capture
|
||||
|
||||
When instant mode is active:
|
||||
|
||||
1. Decide whether the user message contains project-relevant intent.
|
||||
2. Write one raw line per independent thought using `- [HH:MM] original text | suggested-dim:dimension`.
|
||||
3. Do not update mdbase directly; wait for `sortin`.
|
||||
4. Skip ignored messages and ignore intervals.
|
||||
5. Keep normal user work moving. Recording should not block task execution.
|
||||
6. If one day accumulates more than five raw entries, suggest `/ustht sortin`.
|
||||
|
||||
## Sortin and Resort
|
||||
|
||||
`sortin` is soft maintenance:
|
||||
|
||||
1. Read unprocessed `#raw/*.md` files.
|
||||
2. Parse entries and their suggested dimensions.
|
||||
3. Append them to matching `#mdbase/` files grouped by date.
|
||||
4. Mark processed raw files with `<!-- processed -->` on the first line.
|
||||
5. Update `LAST_SORTIN` and the mdbase index.
|
||||
|
||||
`resort` is hard maintenance:
|
||||
|
||||
1. Review all mdbase files.
|
||||
2. Deduplicate overlapping records.
|
||||
3. Move entries into better dimensions when justified by the user's own wording.
|
||||
4. Mark deprecated dimensions instead of deleting them unless the user explicitly requests deletion.
|
||||
5. Preserve provenance and user wording.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Record explicit user decisions faithfully.
|
||||
- Do not over-infer. Store only what the user said or what follows directly from it.
|
||||
- Preserve original wording, including negations, numbers, links, constraints, and tradeoffs.
|
||||
- Split one message into multiple records when it contains independent decisions.
|
||||
- Resolve conflicts by treating the newest user statement as current while preserving the older record as historical context.
|
||||
- Put unmatched project-relevant items in `general.md` instead of inventing too many dimensions.
|
||||
- Do not record unrelated conversation.
|
||||
|
||||
## Limitations
|
||||
|
||||
- The skill records intent; it does not validate whether the user's idea is correct, feasible, secure, or internally consistent.
|
||||
- Dimension assignment depends on agent judgment and may need user correction through `resort`.
|
||||
- Ignore intervals are context-local and do not persist across sessions.
|
||||
- `.ustht/` can contain sensitive information. The skill does not redact content; users must use ignore commands or repository hygiene to manage sensitive data.
|
||||
- The workflow is not file-lock based. In multi-agent environments, agents must coordinate to avoid conflicting writes.
|
||||
|
||||
## Safety Rules
|
||||
|
||||
- Keep all runtime writes inside `#ustht/`.
|
||||
- Validate dimension names: lowercase letters, digits, hyphens, and `/` subdirectories only; no `..`, backslashes, spaces, absolute paths, or reserved names.
|
||||
- Do not execute user-provided shell commands.
|
||||
- Do not recursively copy directories with shell commands during initialization; copy known template files safely.
|
||||
- Treat `<!-- processed -->` as meaningful only when it is the first line of a raw file.
|
||||
- Never silently delete dimension files; mark deprecated content unless the user explicitly asks for deletion.
|
||||
|
||||
More detail is available in `references/safety.md`, `references/sortin.md`, `references/commands.md`, and `references/edge-cases.md`.
|
||||
|
||||
## Related Skills
|
||||
|
||||
None. This skill is intentionally focused on project-local user intent persistence.
|
||||
@@ -0,0 +1,13 @@
|
||||
# user-thoughts Runtime Directory
|
||||
|
||||
This directory stores project-local user intent captured by `user-thoughts`.
|
||||
|
||||
## Contents
|
||||
|
||||
- `define.ini`: runtime state for the skill.
|
||||
- `raw/`: unprocessed user thoughts captured by date.
|
||||
- `ignored/`: entries the user explicitly chose not to record.
|
||||
- `mdbase/`: organized project memory grouped by dimension.
|
||||
- `export/`: exported mdbase content.
|
||||
|
||||
Do not delete this directory unless the user explicitly wants to discard project memory.
|
||||
@@ -0,0 +1,3 @@
|
||||
SKILL_STATUS=on
|
||||
INSTANT_STATUS=off
|
||||
LAST_SORTIN=
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# user-thoughts mdbase Index
|
||||
|
||||
This directory stores user-provided project decisions, constraints, preferences, and plans. Keep the user's original intent intact.
|
||||
|
||||
Last updated: never
|
||||
|
||||
## Maintenance Rules
|
||||
|
||||
- Preserve details from user wording. Do not simplify away constraints, numbers, negations, or examples.
|
||||
- Classify entries by dimension so future agents can find them quickly.
|
||||
- Prefer existing dimensions. Create a new dimension only when the user's thought clearly needs one.
|
||||
- Append new records by date under `## yyyy-mm-dd` headings.
|
||||
- Do not delete historical content unless the user explicitly asks for deletion.
|
||||
|
||||
## Document Index
|
||||
|
||||
| File | Dimension | Entries |
|
||||
|------|-----------|---------|
|
||||
| [backlog.md](backlog.md) | backlog | 0 |
|
||||
| [details/rules.md](details/rules.md) | rules | 0 |
|
||||
| [details/plans.md](details/plans.md) | plans | 0 |
|
||||
| [details/dev-stack.md](details/dev-stack.md) | dev-stack | 0 |
|
||||
| [details/ui/outline.md](details/ui/outline.md) | ui/outline | 0 |
|
||||
| [details/ui/details.md](details/ui/details.md) | ui/details | 0 |
|
||||
| [details/general.md](details/general.md) | general | 0 |
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
# Backlog
|
||||
|
||||
> User plans, pending tasks, and work that has been requested but not started.
|
||||
|
||||
## Pending
|
||||
|
||||
<!-- Items explicitly requested by the user but not started yet. -->
|
||||
|
||||
## In Progress
|
||||
|
||||
<!-- Items that have started but are not complete. -->
|
||||
|
||||
## Done
|
||||
|
||||
<!-- Completed items retained for traceability. -->
|
||||
|
||||
## Notes
|
||||
|
||||
Record the date each item was raised. When an item is completed, move it to Done and include the completion date when known.
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# Development Stack Decisions
|
||||
|
||||
> Frameworks, libraries, services, deployment choices, data stores, APIs, and other technical stack decisions.
|
||||
|
||||
## Current Decisions
|
||||
|
||||
<!-- Append dated user decisions here. -->
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# General Project Notes
|
||||
|
||||
> Project-relevant thoughts that do not fit another dimension yet.
|
||||
|
||||
## Current Notes
|
||||
|
||||
<!-- Append dated user thoughts here. -->
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# Project Plans
|
||||
|
||||
> Directional plans, milestones, priorities, sequencing, and strategic project ideas.
|
||||
|
||||
## Current Plans
|
||||
|
||||
<!-- Append dated user plans here. -->
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# Project Rules and Constraints
|
||||
|
||||
> User-defined rules, constraints, conventions, preferences, and non-negotiables.
|
||||
|
||||
## Current Rules
|
||||
|
||||
<!-- Append dated user rules here. -->
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# UI Details
|
||||
|
||||
> Component-level UI preferences, interaction details, copy details, spacing, states, and visual refinements.
|
||||
|
||||
## Current Details
|
||||
|
||||
<!-- Append dated UI detail decisions here. -->
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
# UI Outline
|
||||
|
||||
> Product-level UI direction, layout concepts, design principles, themes, and screen-level decisions.
|
||||
|
||||
## Current Direction
|
||||
|
||||
<!-- Append dated UI outline decisions here. -->
|
||||
@@ -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
|
||||
```
|
||||
@@ -0,0 +1,62 @@
|
||||
"""Shared helpers for user-thoughts scripts."""
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def find_ustht() -> Path | None:
|
||||
"""Find .ustht/ in the current directory or one of its parents."""
|
||||
cwd = Path.cwd()
|
||||
for d in [cwd, *cwd.parents]:
|
||||
ustht = d / ".ustht"
|
||||
if ustht.is_dir():
|
||||
return ustht
|
||||
return None
|
||||
|
||||
|
||||
def find_skill_dir() -> Path | None:
|
||||
"""Find the installed user-thoughts skill directory."""
|
||||
script_dir = Path(__file__).resolve().parent
|
||||
skill_dir = script_dir.parent
|
||||
if (skill_dir / "SKILL.md").exists():
|
||||
return skill_dir
|
||||
return None
|
||||
|
||||
|
||||
def read_define_ini(ustht: Path) -> dict:
|
||||
"""Read define.ini and return key/value pairs."""
|
||||
ini = ustht / "define.ini"
|
||||
if not ini.exists():
|
||||
return {}
|
||||
result = {}
|
||||
for line in ini.read_text(encoding="utf-8").splitlines():
|
||||
line = line.strip()
|
||||
if "=" in line and not line.startswith("#"):
|
||||
k, v = line.split("=", 1)
|
||||
result[k.strip()] = v.strip()
|
||||
return result
|
||||
|
||||
|
||||
def write_define_ini(ustht: Path, cfg: dict):
|
||||
"""Replace define.ini with the provided key/value pairs."""
|
||||
ini = ustht / "define.ini"
|
||||
lines = [f"{k}={v}" for k, v in cfg.items()]
|
||||
ini.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def is_processed(filepath: Path) -> bool:
|
||||
"""Return true when the first raw-file line is the processed marker."""
|
||||
first_line = filepath.read_text(encoding="utf-8").split("\n", 1)[0].strip()
|
||||
return first_line == "<!-- processed -->"
|
||||
|
||||
|
||||
def validate_dim_name(dim: str) -> bool:
|
||||
"""Validate a dimension path made of safe kebab-case segments."""
|
||||
reserved = {"raw", "ignored", "export", "define", "readme-ai"}
|
||||
if not dim or len(dim) > 64 or ".." in dim or "\\" in dim or " " in dim:
|
||||
return False
|
||||
for part in dim.split("/"):
|
||||
if part in reserved:
|
||||
return False
|
||||
if not part or not re.match(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", part):
|
||||
return False
|
||||
return True
|
||||
@@ -0,0 +1,125 @@
|
||||
"""Manage ignored user-thought entries."""
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht
|
||||
|
||||
HELP = """Usage: python ignore_ops.py show|remove_last|add_suffix "text" [--help]
|
||||
|
||||
Subcommands:
|
||||
show List entries under #ignored/
|
||||
remove_last Remove the latest raw entry and move it to #ignored/
|
||||
add_suffix "text" Add a suffix-ignored entry to #ignored/
|
||||
"""
|
||||
|
||||
|
||||
def find_last_raw_entry(raw_dir: Path):
|
||||
"""Return (file path, line index, entry text) for the latest raw entry."""
|
||||
files = sorted(raw_dir.glob("*.md"), reverse=True)
|
||||
for f in files:
|
||||
lines = f.read_text(encoding="utf-8").splitlines()
|
||||
if lines and lines[0].strip() == "<!-- processed -->":
|
||||
continue
|
||||
for idx in range(len(lines) - 1, -1, -1):
|
||||
if lines[idx].strip().startswith("- ["):
|
||||
return f, idx, lines[idx]
|
||||
return None, None, None
|
||||
|
||||
|
||||
def remove_line(filepath: Path, idx: int):
|
||||
"""Remove one line from a file."""
|
||||
lines = filepath.read_text(encoding="utf-8").splitlines()
|
||||
del lines[idx]
|
||||
filepath.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
|
||||
|
||||
|
||||
def append_to_ignored(ignored_dir: Path, text: str, reason: str):
|
||||
"""Append one ignored entry to today's ignored file."""
|
||||
ignored_dir.mkdir(exist_ok=True)
|
||||
today = datetime.now().strftime("%Y-%m-%d")
|
||||
now = datetime.now().strftime("%H:%M")
|
||||
f = ignored_dir / f"{today}.md"
|
||||
clean = text.strip()
|
||||
if " | suggested-dim:" in clean:
|
||||
clean = clean.rsplit(" | suggested-dim:", 1)[0]
|
||||
entry = f"- [{now}] {clean} ({reason})"
|
||||
if f.exists():
|
||||
content = f.read_text(encoding="utf-8").rstrip()
|
||||
f.write_text(f"{content}\n{entry}\n", encoding="utf-8")
|
||||
else:
|
||||
f.write_text(f"{entry}\n", encoding="utf-8")
|
||||
|
||||
|
||||
def show_ignored(ignored_dir: Path):
|
||||
"""Print all ignored entries."""
|
||||
if not ignored_dir.exists():
|
||||
print("No ignored entries.")
|
||||
return
|
||||
files = sorted(ignored_dir.glob("*.md"), reverse=True)
|
||||
if not files:
|
||||
print("No ignored entries.")
|
||||
return
|
||||
for f in files:
|
||||
entries = [line for line in f.read_text(encoding="utf-8").splitlines() if line.strip().startswith("- [")]
|
||||
if entries:
|
||||
print(f"#{f.name} ({len(entries)} entries):")
|
||||
for entry in entries:
|
||||
print(entry)
|
||||
|
||||
|
||||
def remove_last(ustht: Path):
|
||||
raw_dir = ustht / "raw"
|
||||
if not raw_dir.exists():
|
||||
print("No previous thought to ignore.")
|
||||
return
|
||||
filepath, idx, entry = find_last_raw_entry(raw_dir)
|
||||
if filepath is None:
|
||||
print("No previous thought to ignore.")
|
||||
return
|
||||
remove_line(filepath, idx)
|
||||
append_to_ignored(ustht / "ignored", entry, "ignored with --last")
|
||||
display = entry
|
||||
if "] " in display:
|
||||
display = display.split("] ", 1)[1]
|
||||
if " | suggested-dim:" in display:
|
||||
display = display.rsplit(" | suggested-dim:", 1)[0]
|
||||
print(f"Ignored previous thought: {display}")
|
||||
|
||||
|
||||
def add_suffix(ustht: Path, text: str):
|
||||
append_to_ignored(ustht / "ignored", text, "ignored by suffix")
|
||||
print("Ignored current message.")
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
print(f"Usage: {sys.argv[0]} show|remove_last|add_suffix \"text\"")
|
||||
sys.exit(1)
|
||||
|
||||
cmd = sys.argv[1]
|
||||
if cmd == "show":
|
||||
show_ignored(ustht / "ignored")
|
||||
elif cmd == "remove_last":
|
||||
remove_last(ustht)
|
||||
elif cmd == "add_suffix":
|
||||
if len(sys.argv) < 3:
|
||||
print("Error: add_suffix requires text.")
|
||||
sys.exit(1)
|
||||
add_suffix(ustht, sys.argv[2])
|
||||
else:
|
||||
print(f"Unknown command: {cmd}. Available: show, remove_last, add_suffix")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,63 @@
|
||||
"""Initialize the .ustht/ runtime directory from templates."""
|
||||
import shutil
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_skill_dir
|
||||
|
||||
HELP = """Usage: python init.py [--help]
|
||||
|
||||
Create .ustht/ in the current working directory, copy the runtime templates,
|
||||
and create raw/, ignored/, and export/ directories. Existing .ustht/ content is
|
||||
not overwritten.
|
||||
"""
|
||||
|
||||
|
||||
def copy_template(src: Path, dst: Path):
|
||||
"""Copy template files while skipping symlinks."""
|
||||
for item in src.rglob("*"):
|
||||
rel = item.relative_to(src)
|
||||
target = dst / rel
|
||||
if item.is_symlink():
|
||||
continue
|
||||
if item.is_dir():
|
||||
target.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy2(item, target)
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
target = Path.cwd() / ".ustht"
|
||||
if target.exists():
|
||||
print("Already initialized; .ustht/ exists, skipping creation.")
|
||||
sys.exit(0)
|
||||
|
||||
skill_dir = find_skill_dir()
|
||||
if skill_dir is None:
|
||||
print("Error: SKILL.md was not found. Ensure this script is inside user-thoughts/scripts/.")
|
||||
sys.exit(1)
|
||||
|
||||
template = skill_dir / "assets" / "Runtime-Template"
|
||||
if not template.exists():
|
||||
print(f"Error: template directory does not exist: {template}")
|
||||
sys.exit(1)
|
||||
|
||||
target.mkdir()
|
||||
copy_template(template, target)
|
||||
for name in ["raw", "ignored", "export"]:
|
||||
(target / name).mkdir(exist_ok=True)
|
||||
|
||||
define = target / "define.ini"
|
||||
if not define.exists():
|
||||
define.write_text("SKILL_STATUS=on\nINSTANT_STATUS=off\nLAST_SORTIN=\n", encoding="utf-8")
|
||||
|
||||
print("Initialized .ustht/.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,93 @@
|
||||
"""Show the mdbase index or dimension content."""
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht, validate_dim_name
|
||||
|
||||
HELP = """Usage: python show_mdbase.py show [--all|--dimension] [--help]
|
||||
|
||||
Subcommands:
|
||||
show Show README.ai.md index
|
||||
show --all List all dimensions and entry counts
|
||||
show <dimension> Show one dimension file
|
||||
"""
|
||||
|
||||
|
||||
def show_index(mdbase: Path):
|
||||
index = mdbase / "README.ai.md"
|
||||
if not index.exists():
|
||||
print("mdbase/README.ai.md does not exist.")
|
||||
return
|
||||
print(index.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def list_dims(mdbase: Path):
|
||||
details = mdbase / "details"
|
||||
if not details.exists():
|
||||
return []
|
||||
return sorted(p.relative_to(details).with_suffix("").as_posix() for p in details.rglob("*.md"))
|
||||
|
||||
|
||||
def show_dim(mdbase: Path, dim: str):
|
||||
if not validate_dim_name(dim):
|
||||
print(f"Invalid dimension name: {dim}. Use lowercase letters, digits, hyphens, and optional / subdirectories.")
|
||||
return
|
||||
if dim == "backlog":
|
||||
path = mdbase / "backlog.md"
|
||||
else:
|
||||
path = mdbase / "details" / f"{dim}.md"
|
||||
if not path.exists():
|
||||
print(f"mdbase/details/{dim}.md does not exist yet.")
|
||||
return
|
||||
print(path.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def show_all(mdbase: Path):
|
||||
details = mdbase / "details"
|
||||
if not details.exists():
|
||||
print("mdbase/details/ does not exist.")
|
||||
return
|
||||
dims = list_dims(mdbase)
|
||||
if not dims:
|
||||
print("mdbase has no dimension files.")
|
||||
return
|
||||
print(f"mdbase has {len(dims)} dimensions:")
|
||||
for dim in dims:
|
||||
path = details / f"{dim}.md"
|
||||
lines = [line for line in path.read_text(encoding="utf-8").splitlines() if line.strip().startswith("- ")]
|
||||
print(f" {dim}.md: {len(lines)} entries")
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
mdbase = ustht / "mdbase"
|
||||
if not mdbase.exists():
|
||||
print("mdbase is not initialized. Run /ustht init first.")
|
||||
return
|
||||
|
||||
args = sys.argv[1:]
|
||||
if not args or args[0] != "show":
|
||||
print(f"Usage: {sys.argv[0]} show [--all|--dimension]")
|
||||
sys.exit(1)
|
||||
|
||||
rest = args[1:]
|
||||
if not rest:
|
||||
show_index(mdbase)
|
||||
elif rest[0] == "--all":
|
||||
show_all(mdbase)
|
||||
elif rest[0].startswith("--"):
|
||||
show_dim(mdbase, rest[0][2:])
|
||||
else:
|
||||
show_dim(mdbase, rest[0])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,42 @@
|
||||
"""Show unprocessed raw files."""
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht, is_processed
|
||||
|
||||
HELP = """Usage: python show_raw.py [--help]
|
||||
|
||||
Show unprocessed #raw/ files, including filenames, entry counts, and content.
|
||||
"""
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
raw_dir = ustht / "raw"
|
||||
if not raw_dir.exists():
|
||||
print("No unprocessed records.")
|
||||
return
|
||||
|
||||
files = [f for f in sorted(raw_dir.glob("*.md"), reverse=True) if not is_processed(f)]
|
||||
if not files:
|
||||
print("No unprocessed records. All raw files are marked processed.")
|
||||
return
|
||||
|
||||
for f in files:
|
||||
content = f.read_text(encoding="utf-8").strip()
|
||||
entry_count = sum(1 for line in content.splitlines() if line.strip().startswith("- ["))
|
||||
print(f"#{f.name} ({entry_count} unprocessed entries):")
|
||||
print(content)
|
||||
print()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,211 @@
|
||||
"""Soft-maintain raw user-thought entries into mdbase."""
|
||||
import re
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht, read_define_ini, write_define_ini, is_processed, validate_dim_name
|
||||
|
||||
HELP = """Usage: python sortin.py [--dry] [--help]
|
||||
|
||||
Soft maintenance: parse unprocessed #raw/*.md files, append entries to matching
|
||||
mdbase dimensions, mark raw files as processed, and update LAST_SORTIN.
|
||||
|
||||
Options:
|
||||
--dry Preview changes without writing
|
||||
--help Show this help text
|
||||
"""
|
||||
|
||||
|
||||
def parse_raw_file(filepath: Path):
|
||||
"""Parse raw entries from one file."""
|
||||
entries = []
|
||||
date = filepath.stem.split("-", 3)
|
||||
if len(date) >= 3:
|
||||
date = "-".join(date[:3])
|
||||
else:
|
||||
date = datetime.now().strftime("%Y-%m-%d")
|
||||
|
||||
for line in filepath.read_text(encoding="utf-8").splitlines():
|
||||
line = line.strip()
|
||||
match = re.match(r"^- \[(\d{2}:\d{2})\] (.*)$", line)
|
||||
if not match:
|
||||
continue
|
||||
time, content = match.groups()
|
||||
dim = "general"
|
||||
text = content
|
||||
if " | suggested-dim:" in content:
|
||||
text, dim = content.rsplit(" | suggested-dim:", 1)
|
||||
dim = dim.strip()
|
||||
if not validate_dim_name(dim):
|
||||
dim = "general"
|
||||
entries.append({"time": time, "text": text.strip(), "dimension": dim, "date": date})
|
||||
return entries
|
||||
|
||||
|
||||
def dim_path(mdbase: Path, dim: str) -> Path:
|
||||
"""Return the target file path for a dimension."""
|
||||
if dim == "backlog":
|
||||
return mdbase / "backlog.md"
|
||||
return mdbase / "details" / f"{dim}.md"
|
||||
|
||||
|
||||
def count_entries(path: Path) -> int:
|
||||
if not path.exists():
|
||||
return 0
|
||||
return sum(1 for line in path.read_text(encoding="utf-8").splitlines() if line.strip().startswith("- "))
|
||||
|
||||
|
||||
def append_entries(path: Path, entries):
|
||||
"""Append entries grouped by date to one dimension file."""
|
||||
by_date = defaultdict(list)
|
||||
for entry in entries:
|
||||
by_date[entry["date"]].append(entry)
|
||||
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
if not path.exists():
|
||||
title = path.stem.replace("-", " ").title()
|
||||
path.write_text(f"# {title}\n\n> Project memory for `{path.stem}`.\n\n", encoding="utf-8")
|
||||
|
||||
content = path.read_text(encoding="utf-8").rstrip()
|
||||
for date, date_entries in sorted(by_date.items()):
|
||||
lines = [f"- {entry['text']}" for entry in date_entries]
|
||||
block = "\n".join(lines)
|
||||
heading = f"## {date}"
|
||||
if heading in content:
|
||||
content_lines = content.splitlines()
|
||||
heading_idx = next(i for i, line in enumerate(content_lines) if line.strip() == heading)
|
||||
insert_idx = len(content_lines)
|
||||
for i in range(heading_idx + 1, len(content_lines)):
|
||||
if content_lines[i].startswith("## "):
|
||||
insert_idx = i
|
||||
break
|
||||
before = content_lines[:insert_idx]
|
||||
after = content_lines[insert_idx:]
|
||||
if before and before[-1].strip():
|
||||
before.append("")
|
||||
before.extend(lines)
|
||||
if after:
|
||||
before.append("")
|
||||
before.extend(after)
|
||||
content = "\n".join(before).rstrip()
|
||||
else:
|
||||
content = f"{content}\n\n{heading}\n\n{block}".rstrip()
|
||||
path.write_text(content + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def mark_processed(filepath: Path):
|
||||
"""Insert the processed marker at the top of a raw file."""
|
||||
content = filepath.read_text(encoding="utf-8")
|
||||
if content.split("\n", 1)[0].strip() != "<!-- processed -->":
|
||||
filepath.write_text("<!-- processed -->\n" + content, encoding="utf-8")
|
||||
|
||||
|
||||
def update_index(mdbase: Path):
|
||||
"""Rebuild mdbase/README.ai.md with dimension counts."""
|
||||
now = datetime.now().strftime("%Y-%m-%d %H:%M")
|
||||
details = mdbase / "details"
|
||||
dims = []
|
||||
if details.exists():
|
||||
dims = sorted(p.relative_to(details).with_suffix("").as_posix() for p in details.rglob("*.md"))
|
||||
|
||||
rows = ["| File | Dimension | Entries |", "|------|-----------|---------|"]
|
||||
backlog = mdbase / "backlog.md"
|
||||
if backlog.exists():
|
||||
rows.append(f"| [backlog.md](backlog.md) | backlog | {count_entries(backlog)} |")
|
||||
for dim in dims:
|
||||
path = details / f"{dim}.md"
|
||||
rows.append(f"| [details/{dim}.md](details/{dim}.md) | {dim} | {count_entries(path)} |")
|
||||
|
||||
content = "\n".join([
|
||||
"# user-thoughts mdbase Index",
|
||||
"",
|
||||
"This directory stores user-provided project decisions, constraints, preferences, and plans.",
|
||||
"",
|
||||
f"Last updated: {now}",
|
||||
"",
|
||||
"## Maintenance Rules",
|
||||
"",
|
||||
"- Preserve user wording and constraints.",
|
||||
"- Append entries by date under `## yyyy-mm-dd` headings.",
|
||||
"- Prefer existing dimensions before creating new ones.",
|
||||
"- Mark deprecated content instead of silently deleting history.",
|
||||
"",
|
||||
"## Document Index",
|
||||
"",
|
||||
*rows,
|
||||
"",
|
||||
])
|
||||
(mdbase / "README.ai.md").write_text(content, encoding="utf-8")
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
dry = "--dry" in sys.argv
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
cfg = read_define_ini(ustht)
|
||||
if cfg.get("SKILL_STATUS") == "off":
|
||||
print("SKILL is off; write ignored. Run /ustht skill on to enable it.")
|
||||
sys.exit(0)
|
||||
|
||||
raw_dir = ustht / "raw"
|
||||
if not raw_dir.exists():
|
||||
print("No unprocessed records.")
|
||||
return
|
||||
|
||||
raw_files = [f for f in sorted(raw_dir.glob("*.md")) if not is_processed(f)]
|
||||
if not raw_files:
|
||||
print("No unprocessed records. All raw files are marked processed.")
|
||||
return
|
||||
|
||||
all_entries = []
|
||||
entries_by_file = {}
|
||||
for f in raw_files:
|
||||
entries = parse_raw_file(f)
|
||||
entries_by_file[f] = entries
|
||||
all_entries.extend(entries)
|
||||
|
||||
if not all_entries:
|
||||
print("No valid entries found in raw files.")
|
||||
return
|
||||
|
||||
grouped = defaultdict(list)
|
||||
for entry in all_entries:
|
||||
grouped[entry["dimension"]].append(entry)
|
||||
|
||||
print("Preview mode:" if dry else f"Soft maintenance complete. Processed {len(all_entries)} thoughts:")
|
||||
mdbase = ustht / "mdbase"
|
||||
for dim, entries in sorted(grouped.items()):
|
||||
target = dim_path(mdbase, dim)
|
||||
label = f"{dim}.md" if target.exists() else f"{dim}.md [new dimension]"
|
||||
sample = entries[0]["text"][:60]
|
||||
print(f" -> {label}: +{len(entries)} ({sample})")
|
||||
|
||||
if dry:
|
||||
print(f" {len(all_entries)} total entries; no files were changed.")
|
||||
return
|
||||
|
||||
for dim, entries in grouped.items():
|
||||
append_entries(dim_path(mdbase, dim), entries)
|
||||
|
||||
for f in raw_files:
|
||||
if entries_by_file.get(f):
|
||||
mark_processed(f)
|
||||
|
||||
now = datetime.now().strftime("%Y-%m-%d %H:%M")
|
||||
cfg["LAST_SORTIN"] = now
|
||||
write_define_ini(ustht, cfg)
|
||||
update_index(mdbase)
|
||||
print(f" LAST_SORTIN updated to {now}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,56 @@
|
||||
"""Show current user-thoughts runtime status."""
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht, read_define_ini, is_processed
|
||||
|
||||
HELP = """Usage: python status.py [--help]
|
||||
|
||||
Show SKILL_STATUS, INSTANT_STATUS, LAST_SORTIN, raw file counts, and mdbase
|
||||
dimension counts.
|
||||
"""
|
||||
|
||||
|
||||
def count_raw(raw_dir: Path):
|
||||
"""Return total and unprocessed raw file counts."""
|
||||
if not raw_dir.exists():
|
||||
return 0, 0
|
||||
files = list(raw_dir.glob("*.md"))
|
||||
unprocessed = sum(1 for f in files if not is_processed(f))
|
||||
return len(files), unprocessed
|
||||
|
||||
|
||||
def count_dims(mdbase: Path):
|
||||
"""Count dimension files under mdbase/details/."""
|
||||
details = mdbase / "details"
|
||||
if not details.exists():
|
||||
return 0
|
||||
return len(list(details.rglob("*.md")))
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
cfg = read_define_ini(ustht)
|
||||
skill_status = cfg.get("SKILL_STATUS", "unknown")
|
||||
instant_status = cfg.get("INSTANT_STATUS", "unknown")
|
||||
last_sortin = cfg.get("LAST_SORTIN", "never") or "never"
|
||||
total_raw, unprocessed_raw = count_raw(ustht / "raw")
|
||||
dims = count_dims(ustht / "mdbase")
|
||||
|
||||
print(f"SKILL_STATUS={skill_status}")
|
||||
print(f"INSTANT_STATUS={instant_status}")
|
||||
print(f"LAST_SORTIN={last_sortin}")
|
||||
print(f"raw={unprocessed_raw} unprocessed / {total_raw} total")
|
||||
print(f"dims={dims}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,68 @@
|
||||
"""Toggle SKILL_STATUS and INSTANT_STATUS."""
|
||||
import sys
|
||||
|
||||
from common import find_ustht, read_define_ini, write_define_ini
|
||||
|
||||
HELP = """Usage: python toggle.py skill|instant [on|off] [--help]
|
||||
|
||||
Subcommands:
|
||||
skill Show SKILL_STATUS
|
||||
skill on|off Set SKILL_STATUS
|
||||
instant Show INSTANT_STATUS
|
||||
instant on|off Set INSTANT_STATUS
|
||||
|
||||
Note: instant on requires SKILL_STATUS=on.
|
||||
"""
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
print(f"Usage: {sys.argv[0]} skill|instant [on|off]")
|
||||
sys.exit(1)
|
||||
|
||||
cmd = sys.argv[1]
|
||||
if cmd not in {"skill", "instant"}:
|
||||
print(f"Unknown command: {cmd}. Available: skill, instant")
|
||||
sys.exit(1)
|
||||
|
||||
cfg = read_define_ini(ustht)
|
||||
ini_key = "SKILL_STATUS" if cmd == "skill" else "INSTANT_STATUS"
|
||||
|
||||
if len(sys.argv) == 2:
|
||||
print(f"{ini_key}={cfg.get(ini_key, 'unknown')}")
|
||||
return
|
||||
|
||||
val = sys.argv[2]
|
||||
if val not in {"on", "off"}:
|
||||
print(f"Invalid value: {val}. Available values: on | off")
|
||||
sys.exit(1)
|
||||
|
||||
if cmd == "instant" and val == "on" and cfg.get("SKILL_STATUS") == "off":
|
||||
print("SKILL is off; instant capture cannot be enabled. Run /ustht skill on first.")
|
||||
sys.exit(1)
|
||||
|
||||
cfg[ini_key] = val
|
||||
if cmd == "skill" and val == "off":
|
||||
cfg["INSTANT_STATUS"] = "off"
|
||||
write_define_ini(ustht, cfg)
|
||||
|
||||
if cmd == "skill":
|
||||
if val == "off":
|
||||
print("SKILL is off. Instant capture has been paused.")
|
||||
else:
|
||||
print("SKILL is on.")
|
||||
else:
|
||||
print("Instant capture is on." if val == "on" else "Instant capture is off.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,106 @@
|
||||
"""Append one thought to today's raw file."""
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
from common import find_ustht, read_define_ini, validate_dim_name
|
||||
|
||||
HELP = """Usage: python write_raw.py "thought text" [--dim dimension] [--help]
|
||||
|
||||
Append one thought to today's #raw/ markdown file.
|
||||
|
||||
Arguments:
|
||||
"thought text" Thought text to record (required)
|
||||
--dim dimension Suggested dimension, such as rules or ui/outline
|
||||
--help Show this help text
|
||||
|
||||
Behavior:
|
||||
- If today's raw file is already processed, creates a numbered file such as 2026-06-01-2.md.
|
||||
- If the day has more than five raw entries, suggests /ustht sortin.
|
||||
- If SKILL_STATUS=off, exits without writing.
|
||||
"""
|
||||
|
||||
|
||||
def count_today_raw(raw_dir: Path) -> int:
|
||||
"""Count unprocessed entries across today's raw files."""
|
||||
today = datetime.now().strftime("%Y-%m-%d")
|
||||
count = 0
|
||||
for f in sorted(raw_dir.glob(f"{today}*.md")):
|
||||
content = f.read_text(encoding="utf-8")
|
||||
first_line = content.split("\n", 1)[0].strip()
|
||||
if first_line == "<!-- processed -->":
|
||||
continue
|
||||
count += sum(1 for line in content.splitlines() if line.strip().startswith("- ["))
|
||||
return count
|
||||
|
||||
|
||||
def main():
|
||||
if "--help" in sys.argv or "-h" in sys.argv:
|
||||
print(HELP)
|
||||
sys.exit(0)
|
||||
|
||||
ustht = find_ustht()
|
||||
if ustht is None:
|
||||
print("Error: .ustht/ was not found. Run /ustht init first.")
|
||||
sys.exit(1)
|
||||
|
||||
cfg = read_define_ini(ustht)
|
||||
if cfg.get("SKILL_STATUS") == "off":
|
||||
print("SKILL is off; write ignored.")
|
||||
sys.exit(0)
|
||||
|
||||
thought = None
|
||||
dim = None
|
||||
args = sys.argv[1:]
|
||||
i = 0
|
||||
while i < len(args):
|
||||
if args[i] == "--dim" and i + 1 < len(args):
|
||||
dim = args[i + 1]
|
||||
i += 2
|
||||
elif thought is None:
|
||||
thought = args[i]
|
||||
i += 1
|
||||
else:
|
||||
i += 1
|
||||
|
||||
if not thought:
|
||||
print("Error: missing thought text.")
|
||||
print(f"Usage: {sys.argv[0]} \"thought text\" [--dim dimension]")
|
||||
sys.exit(1)
|
||||
|
||||
if dim and not validate_dim_name(dim):
|
||||
print(f"Invalid dimension name: {dim}. Use lowercase letters, digits, hyphens, and optional / subdirectories.")
|
||||
sys.exit(1)
|
||||
|
||||
raw_dir = ustht / "raw"
|
||||
raw_dir.mkdir(exist_ok=True)
|
||||
|
||||
today = datetime.now().strftime("%Y-%m-%d")
|
||||
now = datetime.now().strftime("%H:%M")
|
||||
raw_file = raw_dir / f"{today}.md"
|
||||
|
||||
if raw_file.exists():
|
||||
first_line = raw_file.read_text(encoding="utf-8").split("\n", 1)[0].strip()
|
||||
if first_line == "<!-- processed -->":
|
||||
seq = 2
|
||||
while (raw_dir / f"{today}-{seq}.md").exists():
|
||||
seq += 1
|
||||
raw_file = raw_dir / f"{today}-{seq}.md"
|
||||
|
||||
thought_clean = thought.replace("\n", " ").replace("\r", "")
|
||||
suffix = f" | suggested-dim:{dim}" if dim else ""
|
||||
entry = f"- [{now}] {thought_clean}{suffix}"
|
||||
|
||||
if raw_file.exists():
|
||||
content = raw_file.read_text(encoding="utf-8").rstrip()
|
||||
raw_file.write_text(f"{content}\n{entry}\n", encoding="utf-8")
|
||||
else:
|
||||
raw_file.write_text(f"{entry}\n", encoding="utf-8")
|
||||
|
||||
count = count_today_raw(raw_dir)
|
||||
if count > 5:
|
||||
print(f"Today has {count} recorded thoughts. Consider running /ustht sortin.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user