@procrastivity/clast 0.0.1 → 0.0.2

package/lib/clast/clast-lib.bash

@@ -11,7 +11,7 @@ fi
 _CLAST_LIB_SOURCED=1
 
 # Hard dependency check: jq must be on PATH. Exit 3 (env problem) per
-# docs/overview.md#exit-codes if missing — no grep/sed fallback.
+# docs/explanation/conventions.md#exit-codes if missing — no grep/sed fallback.
 if ! command -v jq >/dev/null 2>&1; then
   echo "clast: error: required dependency 'jq' not found on PATH" >&2
   exit 3

package/lib/clast/clast-manifest-lib.bash

@@ -2,7 +2,7 @@
 #
 # Sourced after clast-lib.bash. The manifest is an append-only JSONL log at
 # $(clast_journal_dir)/.manifest.jsonl, one line per capture event. Per
-# docs/cli-contract.md#manifest-line each line has seven required fields:
+# docs/reference/cli.md#manifest-line each line has seven required fields:
 # session_id, source, snapshot, captured_at, source_mtime, source_size,
 # day_bucket. Lookups use "most recent line wins" semantics.
 # shellcheck shell=bash
@@ -68,7 +68,7 @@ clast_manifest_append() {
   }
 
   # Append-only single-line write — crash-safe at line boundary per
-  # docs/overview.md#cross-machine-considerations. Do NOT use
+  # docs/explanation/architecture.md#cross-machine-considerations. Do NOT use
   # clast_atomic_write here: it rewrites the whole file and would clobber
   # concurrent appends from another machine.
   local manifest_path

package/lib/clast/clast-registry-lib.bash

@@ -3,8 +3,8 @@
 # Sourced after clast-lib.bash and clast-decode-lib.bash. The registry is
 # an append-only JSONL log at $(clast_journal_dir)/projects.json (the
 # ".json" name is historical — semantically it is JSONL). See
-# docs/cli-contract.md#registry-line-in-projectsjson for the on-disk
-# schema and docs/cli-contract.md#clast-registry for the resolution rules.
+# docs/reference/cli.md#registry-line-in-projectsjson for the on-disk
+# schema and docs/reference/cli.md#clast-registry for the resolution rules.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-decode-lib.bash
@@ -61,13 +61,18 @@ clast_registry_resolve() {
   local arr
   arr="$(clast_registry_list_json)"
 
-  # Segment input: starts with `-`. Decode (possibly ambiguous) then
-  # resolve as a path.
+  # Segment input: starts with `-`. Try raw segment first (handles
+  # segments registered as-is), then decode to filesystem paths.
   if [[ "$input" == -* ]]; then
+    local slug
+    slug="$(_clast_registry_lookup_path "$input" "$arr" 2>/dev/null)" || true
+    if [[ -n "$slug" ]]; then
+      printf '%s\n' "$slug"
+      return 0
+    fi
     local -a candidates=()
     mapfile -t candidates < <(clast_decode_candidates "$input")
-    local c slug
-    # Prefer registry-matching candidate over filesystem-resolving one.
+    local c
     for c in "${candidates[@]}"; do
       slug="$(_clast_registry_lookup_path "$c" "$arr")" || continue
       if [[ -n "$slug" ]]; then
@@ -126,6 +131,8 @@ clast_registry_add() {
         fi
         remote="$2"; remote_explicit=1; shift 2 ;;
       --remote=*) remote="${1#*=}"; remote_explicit=1; shift ;;
+      --)
+        shift; break ;;
       -*)
         clast_log_error "clast_registry_add: unknown flag '$1'"
         return 2
@@ -140,6 +147,19 @@ clast_registry_add() {
     esac
   done
 
+  # Consume remaining positional after --
+  if [[ $# -gt 0 ]]; then
+    if [[ -n "$path" ]]; then
+      clast_log_error "clast_registry_add: unexpected positional '$1'"
+      return 2
+    fi
+    path="$1"; shift
+  fi
+  if [[ $# -gt 0 ]]; then
+    clast_log_error "clast_registry_add: unexpected positional '$1'"
+    return 2
+  fi
+
   # Reject empty / whitespace-only paths.
   local trimmed="${path//[[:space:]]/}"
   if [[ -z "$trimmed" ]]; then

package/lib/clast/clast-subcommands/doctor.bash

@@ -2,7 +2,7 @@
 #
 # Run six sanity checks against the journal and report findings. With
 # `--fix`, perform the two safe repairs (manifest rebuild from disk,
-# orphan-snapshot removal). See docs/cli-contract.md#clast-doctor.
+# orphan-snapshot removal). See docs/reference/cli.md#clast-doctor.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash

package/lib/clast/clast-subcommands/entries.bash

@@ -3,7 +3,7 @@
 # Curated journal entries live at
 #   $(clast_journal_dir)/entries/YYYY-MM-DD-HHMM-<project-slug>-<session-slug>.md
 # as Markdown files with a YAML frontmatter block. See
-# docs/cli-contract.md#clast-entries and docs/cli-contract.md#entry-frontmatter.
+# docs/reference/cli.md#clast-entries and docs/reference/cli.md#entry-frontmatter.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash
@@ -532,7 +532,7 @@ _clast_entries_write() {
   local snapshot_rel mtime
   snapshot_rel="$(jq -r '.snapshot' <<<"$manifest_line")"
   mtime="$(jq -r '.source_mtime' <<<"$manifest_line")"
-  : "$mtime"  # unused for now; reserved for future best-effort fields
+  # curated_source_mtime: stored in frontmatter for stale-curation detection
 
   local seg
   seg="$(awk -F/ 'NR==1{print $3}' <<<"$snapshot_rel")"
@@ -650,6 +650,7 @@ _clast_entries_write() {
   fm+="session_slug: $(_clast_entries_yaml_string "$slug")"$'\n'
   fm+="snapshot_path: $(_clast_entries_yaml_string "$snapshot_rel")"$'\n'
   fm+="machine: $(_clast_entries_yaml_string "$machine")"$'\n'
+  fm+="curated_source_mtime: $(_clast_entries_yaml_string "$mtime")"$'\n'
 
   local composed="---"$'\n'"$fm""---"$'\n\n'"$body"
 

package/lib/clast/clast-subcommands/projects.bash

@@ -1,7 +1,7 @@
 # clast-subcommands/projects.bash — `clast projects`.
 #
 # Read-only view over .manifest.jsonl: list projects (segments) with
-# session activity in a date window. See docs/cli-contract.md#clast-projects.
+# session activity in a date window. See docs/reference/cli.md#clast-projects.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash
@@ -24,7 +24,7 @@ Flags:
   -h, --help         Print this usage and exit.
 
 DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`,
-`-Nd`, or `-Nw`. See docs/cli-contract.md#date-parsing.
+`-Nd`, or `-Nw`. See docs/reference/cli.md#date-parsing.
 EOF
 }
 
@@ -98,7 +98,7 @@ clast_cmd_projects() {
     day_filter="$(clast_today)"
   fi
 
-  # `--until` defaults to `today` per docs/cli-contract.md#clast-projects when
+  # `--until` defaults to `today` per docs/reference/cli.md#clast-projects when
   # `--since` is supplied without an explicit upper bound.
   if [[ -n "$since_date" && -z "$until_date" ]]; then
     until_date="$(clast_today)"

package/lib/clast/clast-subcommands/sessions.bash

@@ -2,29 +2,35 @@
 #
 # Read-only view over .manifest.jsonl: list sessions in a date window,
 # optionally filtered by registry slug. See
-# docs/cli-contract.md#clast-sessions.
+# docs/reference/cli.md#clast-sessions.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash
 # shellcheck source=lib/clast/clast-registry-lib.bash
 # shellcheck source=lib/clast/clast-decode-lib.bash
+# shellcheck source=lib/clast/clast-dismissed-lib.bash
 
 _clast_sessions_usage() {
   cat <<'EOF'
 Usage: clast sessions [--day DATE] [--since DATE] [--until DATE] [--project SLUG]
+       clast sessions dismiss <session-id> [<session-id>...] [--reason TEXT]
 
 List sessions captured in a date window.
 
+Subcommands:
+  dismiss ID...    Mark session(s) as dismissed (excluded from future queries).
+
 Flags:
-  --day DATE       Single-day window (default: today). Mutually exclusive
-                   with --since/--until.
-  --since DATE     Start of range (inclusive).
-  --until DATE     End of range (inclusive).
-  --project SLUG   Filter to a single registry slug.
-  -h, --help       Print this usage and exit.
+  --day DATE              Single-day window (default: today). Mutually exclusive
+                          with --since/--until.
+  --since DATE            Start of range (inclusive).
+  --until DATE            End of range (inclusive).
+  --project SLUG          Filter to a single registry slug.
+  --include-dismissed     Include dismissed sessions in results.
+  -h, --help              Print this usage and exit.
 
 DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`,
-`-Nd`, or `-Nw`. See docs/cli-contract.md#date-parsing.
+`-Nd`, or `-Nw`. See docs/reference/cli.md#date-parsing.
 EOF
 }
 
@@ -37,9 +43,72 @@ _clast_sessions_err() {
   fi
 }
 
+# _clast_sessions_dismiss <id> [<id>...] [--reason TEXT]
+_clast_sessions_dismiss() {
+  if [[ $# -eq 0 ]]; then
+    _clast_sessions_err "dismiss requires at least one session ID"
+    return 2
+  fi
+
+  source "$CLAST_LIB/clast-dismissed-lib.bash"
+
+  local -a ids=()
+  local reason=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --reason)
+        if [[ $# -lt 2 ]]; then _clast_sessions_err "--reason requires a value"; return 2; fi
+        reason="$2"; shift 2 ;;
+      --reason=*)
+        reason="${1#*=}"; shift ;;
+      -h|--help)
+        _clast_sessions_usage; return 0 ;;
+      -*)
+        _clast_sessions_err "dismiss: unknown flag '$1'"; return 2 ;;
+      *)
+        ids+=("$1"); shift ;;
+    esac
+  done
+
+  if [[ ${#ids[@]} -eq 0 ]]; then
+    _clast_sessions_err "dismiss requires at least one session ID"
+    return 2
+  fi
+
+  local id count=0
+  for id in "${ids[@]}"; do
+    if ! [[ "$id" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]]; then
+      _clast_sessions_err "dismiss: '$id' is not a valid UUID"
+      return 2
+    fi
+    if clast_dismissed_check "$id"; then
+      if [[ -z "${CLAST_QUIET:-}" ]]; then
+        clast_log_info "already dismissed: $id"
+      fi
+      continue
+    fi
+    clast_dismissed_add "$id" "$reason"
+    count=$(( count + 1 ))
+  done
+
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -cn --argjson count "$count" '{dismissed: $count}'
+  elif [[ -z "${CLAST_QUIET:-}" ]]; then
+    clast_log_info "Dismissed $count session(s)."
+  fi
+}
+
 clast_cmd_sessions() {
+  # Handle "sessions dismiss" sub-action before flag parsing.
+  if [[ "${1:-}" == "dismiss" ]]; then
+    shift
+    _clast_sessions_dismiss "$@"
+    return $?
+  fi
+
   local day_filter="" since_date="" until_date=""
   local project_filter=""
+  local include_dismissed=0
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -81,6 +150,10 @@ clast_cmd_sessions() {
         project_filter="$2"; shift 2 ;;
       --project=*)
         project_filter="${1#*=}"; shift ;;
+      --include-dismissed)
+        include_dismissed=1; shift ;;
+      --json)
+        export CLAST_JSON=1; shift ;;
       -h|--help)
         _clast_sessions_usage; return 0 ;;
       --)
@@ -101,7 +174,7 @@ clast_cmd_sessions() {
     day_filter="$(clast_today)"
   fi
 
-  # `--until` defaults to `today` per docs/cli-contract.md#clast-sessions
+  # `--until` defaults to `today` per docs/reference/cli.md#clast-sessions
   # when `--since` is supplied without an explicit upper bound.
   if [[ -n "$since_date" && -z "$until_date" ]]; then
     until_date="$(clast_today)"
@@ -113,6 +186,13 @@ clast_cmd_sessions() {
   local journal_dir
   journal_dir="$(clast_journal_dir)"
 
+  # Build dismissed set unless --include-dismissed was passed.
+  source "$CLAST_LIB/clast-dismissed-lib.bash"
+  declare -A dismissed_ids=()
+  if (( include_dismissed == 0 )); then
+    clast_dismissed_set dismissed_ids
+  fi
+
   # Build the project segment whitelist if --project was passed.
   declare -A allowed_segs=()
   local have_project_filter=0
@@ -134,6 +214,10 @@ clast_cmd_sessions() {
     [[ -z "$line" ]] && continue
     sid="$(jq -r '.session_id' <<<"$line")"
     [[ -z "$sid" || "$sid" == "null" ]] && continue
+    # Skip dismissed sessions early to avoid unnecessary work.
+    if [[ -n "${dismissed_ids[$sid]:-}" ]]; then
+      continue
+    fi
     latest_line["$sid"]="$line"
   done < <(clast_manifest_iterate "$filter")
 
@@ -183,12 +267,33 @@ clast_cmd_sessions() {
     branch=""
 
     curated=false
+    local stale=false
     if [[ -d "$entries_dir" ]]; then
-      if grep -l "session_id: $sid" "$entries_dir"/*.md 2>/dev/null | head -n1 | grep -q .; then
+      local entry_matches
+      entry_matches="$(grep -l "session_id: $sid" "$entries_dir"/*.md 2>/dev/null)" || true
+      if [[ -n "$entry_matches" ]]; then
         curated=true
+        local best_curated_mtime="" ef cm
+        while IFS= read -r ef; do
+          [[ -z "$ef" ]] && continue
+          cm="$(grep '^curated_source_mtime:' "$ef" 2>/dev/null | head -n1 | sed 's/^curated_source_mtime:[[:space:]]*//')" || true
+          cm="${cm#\"}"
+          cm="${cm%\"}"
+          if [[ -n "$cm" && ( -z "$best_curated_mtime" || "$cm" > "$best_curated_mtime" ) ]]; then
+            best_curated_mtime="$cm"
+          fi
+        done <<<"$entry_matches"
+        if [[ -n "$best_curated_mtime" && "$best_curated_mtime" != "$mtime" ]]; then
+          stale=true
+        fi
       fi
     fi
 
+    local is_dismissed=false
+    if [[ -n "${dismissed_ids[$sid]:-}" ]]; then
+      is_dismissed=true
+    fi
+
     rows+=("$(jq -cn \
       --arg session_id "$sid" \
       --arg project "$slug" \
@@ -200,6 +305,8 @@ clast_cmd_sessions() {
       --arg snapshot_path "$snapshot" \
       --arg day_bucket "$day_bucket" \
       --argjson curated "$curated" \
+      --argjson stale "$stale" \
+      --argjson dismissed "$is_dismissed" \
       '{
          session_id: $session_id,
          project: $project,
@@ -210,7 +317,9 @@ clast_cmd_sessions() {
          msg_count_approx: $msg_count_approx,
          snapshot_path: $snapshot_path,
          day_bucket: $day_bucket,
-         curated: $curated
+         curated: $curated,
+         stale: $stale,
+         dismissed: $dismissed
        }')")
   done
 

package/lib/clast/clast-subcommands/show.bash

@@ -1,7 +1,7 @@
 # clast-subcommands/show.bash — `clast show <session-id>`.
 #
 # Dump metadata + (optionally) first/last turns of a single captured
-# session. See docs/cli-contract.md#clast-show.
+# session. See docs/reference/cli.md#clast-show.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash

package/lib/clast/clast-subcommands/snapshot.bash

@@ -28,7 +28,7 @@ EOF
 
 # _clast_snapshot_bucket_for_epoch <epoch>
 #   Mirror of clast_today's cutoff math against an arbitrary epoch. Local
-#   time per docs/overview.md#conventions.
+#   time per docs/explanation/conventions.md.
 _clast_snapshot_bucket_for_epoch() {
   local epoch="$1"
   local cutoff="${CLAST_DAY_CUTOFF:-04:00}"
@@ -247,7 +247,7 @@ _clast_snapshot_emit_summary() {
   fi
 
   # Silent no-op: load-bearing for the SessionStart hook (step 11). Re-read
-  # docs/cli-contract.md#clast-snapshot before changing this.
+  # docs/reference/cli.md#clast-snapshot before changing this.
   if (( ${#_caps[@]} == 0 && ${#_errs[@]} == 0 )); then
     return 0
   fi

package/lib/clast/clast-subcommands/stats.bash

@@ -2,7 +2,7 @@
 #
 # Read-only summary of journal activity over a date window using manifest
 # + filesystem stat only. No JSONL body parsing. See
-# docs/cli-contract.md#clast-stats.
+# docs/reference/cli.md#clast-stats.
 # shellcheck shell=bash
 # shellcheck source=lib/clast/clast-lib.bash
 # shellcheck source=lib/clast/clast-manifest-lib.bash
@@ -23,7 +23,7 @@ Flags:
   -h, --help       Print this usage and exit.
 
 DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`,
-`-Nd`, or `-Nw`. See docs/cli-contract.md#date-parsing.
+`-Nd`, or `-Nw`. See docs/reference/cli.md#date-parsing.
 EOF
 }
 

package/lib/clast/prompts/brief-system.md

@@ -0,0 +1,31 @@
+You are synthesizing a project briefing for the user. They are about to start work on a project and want a tight summary of where they left off.
+
+Produce a briefing using this structure (omit any section that has no content):
+
+## Wakeup briefing — {project}
+
+**Active thread:** one-line from most recent entry's "Open threads", or "None"
+
+**Last session:** date, branch, one-line goal
+- Work done: 2-3 bullets condensed from most recent entry
+- Open threads: bullets, if any
+- Dead ends to avoid: bullets, if any
+
+**Recent sessions:** (up to 5 entries)
+- date [branch] slug: one-line goal
+
+**Today's breadcrumbs:** (if any)
+- HH:MM — text
+
+**Today's sessions:** (if user has already worked today)
+- HH:MM start: branch, msg-count messages
+
+**Suggested next step:** derived from active thread + breadcrumbs
+
+Be concise. Use the user's terminology. Don't repeat content across sections. The total briefing should be 2-5k tokens — if you're approaching that, summarize rather than list verbatim.
+
+For the "Suggested next step": prefer the most recent entry's "Open threads" content, then the most recent breadcrumb, then a synthesis of the recent work. If nothing concrete, say "No active thread."
+
+End with one of:
+- "Resume? Active thread: '<thread>'. Suggested next step: <step>."
+- "No active thread. Last session ended cleanly. What are you working on today?"

package/lib/clast/prompts/brief-user.md

@@ -0,0 +1,10 @@
+Project: {{project}}
+
+Recent curated entries (newest first):
+{{entries}}
+
+Today's breadcrumbs for this project:
+{{breadcrumbs}}
+
+Today's session activity for this project:
+{{sessions}}

package/lib/clast/prompts/day-wakeup-draft-system.md

@@ -0,0 +1,28 @@
+You are drafting a journal entry for a Claude Code session that the user just reviewed. The entry will be written to the user's journal and may be read days or weeks later to refresh context on what was happening.
+
+Draft a journal entry in this exact markdown structure. Omit any section that has no content (do not write "N/A"):
+
+# Session: <short human-readable title>
+
+## Goal
+One sentence describing what this session was trying to accomplish.
+
+## What shipped
+- Bullet list of what actually got done (files written, features built, fixes landed). Extract from the transcript.
+
+## Issues + fixes
+- **Issue:** what broke. **Fix:** what resolved it.
+
+## Dead ends touched
+- **Tried:** approach.
+  - Note: if you cannot tell *why* an approach was abandoned from the transcript, leave that for the user to fill in. Do not speculate.
+
+## Open threads
+- Anything still unfinished or deferred. Use the breadcrumbs and the last turns of the session as signal.
+
+## Notes
+- Anything else useful for the next session in this project.
+
+Be concise. Prefer bullets over paragraphs. Use the user's terminology (project-specific names, file paths). Do not invent details. If you are uncertain about something, omit it rather than guess.
+
+After the entry, add a blank line and then: "Suggested tags: tag1, tag2, tag3"

package/lib/clast/prompts/day-wakeup-draft-user.md

@@ -0,0 +1,15 @@
+Session metadata:
+- Project: {{project}}
+- Branch: {{branch}}
+- Start: {{start}}
+- End: {{end}}
+- Approximate messages: {{msg_count}}
+
+First turns of the session:
+{{first_turns}}
+
+Last turns of the session:
+{{last_turns}}
+
+Breadcrumbs the user left during this session's day:
+{{breadcrumbs}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@procrastivity/clast",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Capture, curate, and surface Claude Code session history across all your projects.",
   "homepage": "https://github.com/procrastivity/clast#readme",
   "bin": {