create-egregore 0.19.8 → 0.19.11

package/runtime/pi/bin/graph-op.sh

@@ -6,17 +6,19 @@ set -euo pipefail
 # Usage: bash bin/graph-op.sh <operation> [args...]
 #
 # Operations:
-#   mark-read <session-id>      Mark a handoff as read
-#   mark-done <session-id>      Mark a handoff as done/resolved
+#   mark-read <session-id> [user]     Mark a handoff as read
+#   mark-done <session-id> [user]     Mark a handoff as done/resolved
+#   mark-expired <session-id> [user]  Explicitly expire an open handoff
+#   reopen-handoff <session-id> [user] Reopen a terminal handoff
 #   answer-question <set-id>    Mark a question set as answered
-#   resolve-handoffs <user>     Auto-resolve read handoffs with later sessions
+#   resolve-handoffs <user>     Resolve completed explicit implementation lineage
 #   set-topic <session-id> <topic> [branch]
 #                               Set topic (and optionally branch) on a Session node
 #   record-focus <session-id> <shown-json> <selected> [dismissed-json]
 #                               Track Focus option selection for adaptive options
-#   merge-person <keep-name> <remove-name>
-#                               Merge two Person nodes — transfers relationships from
-#                               remove-name to keep-name, stores remove-name as alias
+#   merge-person <keep-name> <alias-name>
+#                               Reconcile two Person nodes — projects relationships
+#                               to keep-name and retains alias-name append-only
 #   create-harvest <id> <topic> <intent> <initiator>
 #                               Create a Harvest node and link to initiator (WAL-backed)
 #   create-harvest-session <harvest-id> <session-id> <person-name> [status]
@@ -28,6 +30,14 @@ set -euo pipefail
 #                               Record a question-answer turn in a HarvestSession
 #   complete-harvest <harvest-id> <artifact-path>
 #                               Mark harvest complete and link synthesis artifact
+#   catalog                     List bounded read operations and their contracts
+#   open-handoffs <user> [limit] Read non-terminal handoffs addressed to a person
+#   pending-questions <user> [limit] Read active question sets awaiting a person
+#   lineage <topic> [limit]     Trace matching sessions, handoffs, implementations,
+#                               PRs, and canonical evidence files
+#   meeting-history <query> [limit]
+#                               Find a meeting sequence, participants, derived
+#                               knowledge, and unprojected canonical meeting files
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 
@@ -37,50 +47,287 @@ if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   echo "Named graph operations — clean interface over raw Cypher."
   echo ""
   echo "Operations:"
-  echo "  mark-read <sid>          Mark handoff as read"
-  echo "  mark-done <sid>          Mark handoff as done"
+  echo "  mark-read <sid> [user]       Mark handoff as read"
+  echo "  mark-done <sid> [user]       Mark handoff as done"
+  echo "  mark-expired <sid> [user]    Explicitly expire an open handoff"
+  echo "  reopen-handoff <sid> [user]  Reopen a done/expired handoff"
   echo "  answer-question <qid>    Mark question set as answered"
-  echo "  resolve-handoffs <user>  Auto-resolve read handoffs"
+  echo "  resolve-handoffs <user>  Resolve completed implementation lineage"
   echo "  set-topic <sid> <topic>  Set topic on a Session node"
-  echo "  merge-person <keep> <rm> Merge two Person nodes"
+  echo "  merge-person <keep> <alias> Reconcile a Person as a canonical alias"
   echo "  claim-handoff <sid> <ho> Link implementing session to handoff"
   echo "  create-pr <sid> <num> <repo> <author> [title]"
   echo "  register-artifact <id> <url> <title> <type> <author> <topics> <excerpt>"
   echo "  create-harvest / complete-harvest / record-harvest-turn"
+  echo "  catalog                        List bounded read operation contracts"
+  echo "  open-handoffs <user> [n]     Read recent non-terminal handoffs"
+  echo "  pending-questions <user> [n] Read recent active question sets"
+  echo "  lineage <topic> [n]          Trace handoff/implementation/PR evidence"
+  echo "  meeting-history <query> [n] Find meeting continuity and coverage gaps"
   echo "  wal-status               Show WAL pending count"
   exit 0
 fi
 
+GS="$SCRIPT_DIR/bin/graph.sh"
+
+OP="${1:-}"
+shift || true
+
 # --- Local mode gate: bail immediately ---
 _MODE=$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+
+# The catalog is static runtime metadata, not a graph read. Keep it available
+# in local mode so every harness can route correctly without opening this file
+# or guessing whether an operation exists.
+if [ "$OP" = "catalog" ]; then
+  jq -n --arg mode "$_MODE" '{
+    schema: "egregore.graph-operation-catalog/v1",
+    definitionVersion: 1,
+    mode: $mode,
+    operations: [
+      {
+        name: "open-handoffs",
+        intent: "current non-terminal handoffs addressed to a person",
+        usage: "bash bin/graph-op.sh open-handoffs <user> [limit]",
+        availability: "connected",
+        maxResults: 25,
+        evidence: "live graph state"
+      },
+      {
+        name: "pending-questions",
+        intent: "current active question sets awaiting a person",
+        usage: "bash bin/graph-op.sh pending-questions <user> [limit]",
+        availability: "connected",
+        maxResults: 25,
+        evidence: "live graph state"
+      },
+      {
+        name: "lineage",
+        intent: "handoff to implementation, branch, PR, and superseding direction",
+        usage: "bash bin/graph-op.sh lineage <topic> [limit]",
+        availability: "connected",
+        maxResults: 15,
+        evidence: "graph relationships plus canonical file pointers"
+      },
+      {
+        name: "meeting-history",
+        intent: "cross-meeting continuity for a company, person, or topic",
+        usage: "bash bin/graph-op.sh meeting-history <query> [limit]",
+        availability: "connected",
+        maxResults: 15,
+        evidence: "projected meeting relationships plus canonical file coverage"
+      }
+    ]
+  }'
+  exit 0
+fi
+
 if [ "$_MODE" = "local" ]; then
   echo '{"results":[]}'
   exit 0
 fi
 
-GS="$SCRIPT_DIR/bin/graph.sh"
+# Return a bounded set of exact canonical paths containing a literal query.
+# This is intentionally a coverage check around graph results, not a second
+# full-text answer corpus: agents still open only the relevant canonical files.
+memory_file_candidates() {
+  local query="$1"
+  local limit="$2"
+  shift 2
+  local filename_hits=""
+  local content_hits=""
+  local hits=""
 
-OP="${1:-}"
-shift || true
+  if command -v rg >/dev/null 2>&1; then
+    filename_hits="$(
+      rg --files --glob '*.md' --glob '!index.md' "$@" 2>/dev/null \
+        | sort \
+        | while IFS= read -r path; do
+            printf '%s' "$path" | grep -Fqi -- "$query" \
+              && printf 'filename\t%s\n' "$path"
+          done || true
+    )"
+    content_hits="$(
+      rg -i -l -F --glob '*.md' --glob '!index.md' -- "$query" "$@" 2>/dev/null \
+        | sort \
+        | while IFS= read -r path; do printf 'content\t%s\n' "$path"; done || true
+    )"
+  else
+    content_hits="$(
+      find -L "$@" -type f -name '*.md' -print 2>/dev/null \
+        | while IFS= read -r path; do
+            [ "$(basename "$path")" = "index.md" ] && continue
+            printf '%s' "$path" | grep -Fqi -- "$query" \
+              && printf 'filename\t%s\n' "$path"
+            grep -Fqi -- "$query" "$path" 2>/dev/null \
+              && printf 'content\t%s\n' "$path"
+          done || true
+    )"
+  fi
+
+  hits="$(
+    printf '%s\n%s\n' "$filename_hits" "$content_hits" \
+      | awk -F '	' 'NF >= 2 && !seen[$2]++' \
+      | head -n "$limit"
+  )"
+
+  while IFS=$'\t' read -r match_kind path; do
+    [ -n "$path" ] || continue
+    case "$path" in
+      "$SCRIPT_DIR"/memory/*)
+        printf 'memory/%s\t%s\n' "${path#"$SCRIPT_DIR"/memory/}" "$match_kind"
+        ;;
+    esac
+  done <<< "$hits" | jq -Rsc '
+    split("\n")
+    | map(select(length > 0))
+    | map(split("\t") | {evidencePath: .[0], matchKind: .[1]})
+  '
+}
+
+# Reduce natural-language read queries to a small set of discriminative terms.
+# Named reads should tolerate "42CAP Moritz partner call" without requiring that
+# exact phrase to exist in a graph property or canonical Markdown file.
+meaningful_query_terms() {
+  jq -Rn --arg query "$1" '
+    [
+      $query
+      | ascii_downcase
+      | scan("[a-z0-9][a-z0-9._+-]*")
+      | select(length >= 3)
+      | select(. as $term |
+          [
+            "about","across","after","before","between","call","calls",
+            "company","conversation","evolved","first","from","history",
+            "later","meeting","meetings","month","partner","partners",
+            "person","the","topic","transcript","transcripts","what","with"
+          ]
+          | index($term) == null
+        )
+    ]
+    | unique
+    | if length == 0 then [$query | ascii_downcase] else .[0:8] end
+  '
+}
+
+# Build a bounded union of literal coverage checks for each meaningful term.
+# The result remains a list of exact canonical paths, not a second answer corpus.
+memory_file_candidates_for_terms() {
+  local terms_json="$1"
+  local limit="$2"
+  shift 2
+  local combined='[]'
+  local term=""
+  local term_hits=""
+
+  while IFS= read -r term; do
+    [ -n "$term" ] || continue
+    term_hits="$(memory_file_candidates "$term" "$limit" "$@")"
+    combined="$(
+      jq -n \
+        --argjson prior "$combined" \
+        --argjson next "$term_hits" \
+        --argjson limit "$limit" '
+          ($prior + $next)
+          | unique_by(.evidencePath)
+          | .[0:$limit]
+        '
+    )"
+  done < <(printf '%s' "$terms_json" | jq -r '.[]')
+
+  printf '%s\n' "$combined"
+}
 
 case "$OP" in
 
   mark-read)
     SID="${1:?missing session-id}"
+    USER="${2:-}"
     bash "$GS" query "
       MATCH (s:Session {id: \$sid})
-      SET s.handoffStatus = 'read', s.handoffReadDate = date()
-      RETURN s.id AS id, s.topic AS topic
-    " "$(jq -n --arg sid "$SID" '{sid: $sid}')"
+      OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+      WITH s, collect(DISTINCT recipient) AS recipients
+      WHERE (\$user = '' OR any(p IN recipients WHERE
+        toLower(p.name) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)))
+        AND coalesce(s.handoffStatus, 'pending') IN ['pending','read']
+      SET s.handoffReadDate = coalesce(s.handoffReadDate, date()),
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleVersion = 1
+      FOREACH (_ IN CASE WHEN s.handoffIntent = 'fyi' THEN [1] ELSE [] END |
+        SET s.handoffStatus = 'done',
+            s.handoffDoneAt = coalesce(s.handoffDoneAt, datetime()),
+            s.handoffLifecycleReason = 'fyi_read')
+      FOREACH (_ IN CASE WHEN coalesce(s.handoffIntent, 'unclassified') <> 'fyi' THEN [1] ELSE [] END |
+        SET s.handoffStatus = 'read',
+            s.handoffLifecycleReason = 'recipient_read')
+      RETURN s.id AS id, s.topic AS topic, s.handoffStatus AS status,
+             coalesce(s.handoffIntent, 'unclassified') AS intent
+    " "$(jq -n --arg sid "$SID" --arg user "$USER" '{sid: $sid,user: $user}')"
     ;;
 
   mark-done)
     SID="${1:?missing session-id}"
+    USER="${2:-}"
     bash "$GS" query "
       MATCH (s:Session {id: \$sid})
-      SET s.handoffStatus = 'done'
-      RETURN s.id AS id, s.topic AS topic
-    " "$(jq -n --arg sid "$SID" '{sid: $sid}')"
+      OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+      WITH s, collect(DISTINCT recipient) AS recipients
+      WHERE (\$user = '' OR any(p IN recipients WHERE
+        toLower(p.name) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)))
+        AND coalesce(s.handoffStatus, 'pending') IN ['pending','read','claimed']
+      SET s.handoffStatus = 'done',
+          s.handoffDoneAt = datetime(),
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleReason = 'explicit_done',
+          s.handoffLifecycleVersion = 1
+      RETURN s.id AS id, s.topic AS topic, s.handoffStatus AS status
+    " "$(jq -n --arg sid "$SID" --arg user "$USER" '{sid: $sid,user: $user}')"
+    ;;
+
+  mark-expired)
+    SID="${1:?missing session-id}"
+    USER="${2:-}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+      WITH s, collect(DISTINCT recipient) AS recipients
+      WHERE (\$user = '' OR any(p IN recipients WHERE
+        toLower(p.name) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)))
+        AND coalesce(s.handoffStatus, 'pending') IN ['pending','read','claimed']
+      SET s.handoffStatus = 'expired',
+          s.handoffExpiredAt = datetime(),
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleReason = 'explicit_expired',
+          s.handoffLifecycleVersion = 1
+      RETURN s.id AS id, s.topic AS topic, s.handoffStatus AS status
+    " "$(jq -n --arg sid "$SID" --arg user "$USER" '{sid: $sid,user: $user}')"
+    ;;
+
+  reopen-handoff)
+    SID="${1:?missing session-id}"
+    USER="${2:-}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+      WITH s, collect(DISTINCT recipient) AS recipients
+      WHERE (\$user = '' OR any(p IN recipients WHERE
+        toLower(p.name) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)))
+        AND s.handoffStatus IN ['done','expired','completed']
+      SET s.handoffLastDoneAt = s.handoffDoneAt,
+          s.handoffLastExpiredAt = s.handoffExpiredAt,
+          s.handoffDoneAt = null,
+          s.handoffExpiredAt = null,
+          s.handoffStatus = 'pending',
+          s.handoffReopenedAt = datetime(),
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleReason = 'explicit_reopened',
+          s.handoffLifecycleVersion = 1
+      RETURN s.id AS id, s.topic AS topic, s.handoffStatus AS status
+    " "$(jq -n --arg sid "$SID" --arg user "$USER" '{sid: $sid,user: $user}')"
     ;;
 
   answer-question)
@@ -96,13 +343,20 @@ case "$OP" in
     USER="${1:?missing username}"
     bash "$GS" query "
       MATCH (s:Session)-[:HANDED_TO]->(p:Person {name: \$user})
-      WHERE s.handoffStatus = 'read'
-      WITH s, p, coalesce(s.handoffReadDate, s.date) AS sinceDate
-      MATCH (later:Session)-[:BY]->(p)
-      WHERE later.date > sinceDate
-      WITH s, count(later) AS laterSessions WHERE laterSessions > 0
-      SET s.handoffStatus = 'done'
-      RETURN s.id AS resolved
+      WHERE s.handoffStatus IN ['read','claimed']
+      WITH DISTINCT s, p, size([(s)-[:HANDED_TO]->(:Person) | 1]) AS recipientCount
+      WHERE recipientCount = 1
+      MATCH (implementation:Session)-[:IMPLEMENTS]->(s)
+      MATCH (implementation)-[:BY]->(p)
+      WHERE implementation.wrappedAt IS NOT NULL
+         OR implementation.status IN ['completed','handed_off','wrapped']
+      WITH DISTINCT s, implementation
+      SET s.handoffStatus = 'done',
+          s.handoffDoneAt = coalesce(s.handoffDoneAt, datetime()),
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleReason = 'single_recipient_implemented',
+          s.handoffLifecycleVersion = 1
+      RETURN s.id AS resolved, implementation.id AS implementation
     " "$(jq -n --arg user "$USER" '{user: $user}')"
     ;;
 
@@ -141,34 +395,110 @@ case "$OP" in
 
   merge-person)
     KEEP="${1:?missing keep-name (the Person to keep)}"
-    REMOVE="${2:?missing remove-name (the Person to absorb)}"
+    ALIAS="${2:?missing alias-name (the Person to reconcile)}"
     bash "$GS" query "
-      MATCH (keep:Person) WHERE toLower(keep.name) = toLower(\$keep) OR keep.github = \$keep
-      MATCH (remove:Person) WHERE toLower(remove.name) = toLower(\$remove) OR remove.github = \$remove
-      WITH keep, remove WHERE keep <> remove
-      SET keep.previousNames = coalesce(keep.previousNames, []) + remove.name
-      WITH keep, remove
-      OPTIONAL MATCH (s1)-[:BY]->(remove)
+      MATCH (keep:Person) WHERE (toLower(keep.name) = toLower(\$keep) OR toLower(keep.github) = toLower(\$keep) OR keep.personId = \$keep OR toLower(\$keep) IN [x IN coalesce(keep.githubAliases, []) | toLower(x)] OR toLower(\$keep) IN [x IN coalesce(keep.emails, []) | toLower(x)])
+        AND NOT coalesce(keep.kind, '') IN ['external', 'identity_alias']
+        AND coalesce(keep.status, 'active') = 'active' AND keep.ingestRef IS NULL
+      MATCH (alias:Person) WHERE (toLower(alias.name) = toLower(\$alias) OR toLower(alias.github) = toLower(\$alias) OR alias.personId = \$alias OR toLower(\$alias) IN [x IN coalesce(alias.githubAliases, []) | toLower(x)] OR toLower(\$alias) IN [x IN coalesce(alias.emails, []) | toLower(x)])
+        AND NOT coalesce(alias.kind, '') IN ['external', 'identity_alias']
+        AND coalesce(alias.status, 'active') = 'active' AND alias.ingestRef IS NULL
+      WITH keep, alias WHERE keep <> alias
+        AND (
+          keep.githubId IS NULL OR alias.githubId IS NULL
+          OR toString(keep.githubId) = toString(alias.githubId)
+        )
+        AND NOT (
+          coalesce(keep.personId, '') STARTS WITH 'github:'
+          AND coalesce(alias.personId, '') STARTS WITH 'github:'
+          AND keep.personId <> alias.personId
+        )
+      SET keep.previousNames = reduce(
+            acc = coalesce(keep.previousNames, []),
+            value IN coalesce(alias.previousNames, []) + [alias.name, alias.displayName] |
+            CASE WHEN value IS NULL OR toLower(value) = toLower(keep.name) OR value IN acc
+              THEN acc ELSE acc + value END
+          ),
+          keep.githubAliases = reduce(
+            acc = coalesce(keep.githubAliases, []),
+            value IN coalesce(alias.githubAliases, []) + [alias.github] |
+            CASE WHEN value IS NULL OR toLower(value) = toLower(keep.github) OR value IN acc
+              THEN acc ELSE acc + value END
+          ),
+          keep.emails = reduce(
+            acc = coalesce(keep.emails, []),
+            value IN coalesce(alias.emails, []) + [alias.email] |
+            CASE WHEN value IS NULL OR value IN acc THEN acc ELSE acc + value END
+          ),
+          keep.joined = coalesce(alias.joined, keep.joined),
+          keep.invited = coalesce(keep.invited, alias.invited),
+          keep.invitedBy = coalesce(keep.invitedBy, alias.invitedBy),
+          keep.role = coalesce(keep.role, alias.role),
+          keep.domain = coalesce(keep.domain, alias.domain),
+          keep.focus = coalesce(keep.focus, alias.focus),
+          keep.workStyle = coalesce(keep.workStyle, alias.workStyle),
+          keep.telegramId = coalesce(keep.telegramId, alias.telegramId),
+          keep.lastBrief = coalesce(keep.lastBrief, alias.lastBrief),
+          keep.lastBriefDate = coalesce(keep.lastBriefDate, alias.lastBriefDate),
+          keep.lastRecommendations = coalesce(keep.lastRecommendations, alias.lastRecommendations)
+      WITH keep, alias
+      OPTIONAL MATCH (s1:Session)-[:BY]->(alias)
       FOREACH (_ IN CASE WHEN s1 IS NOT NULL THEN [1] ELSE [] END | MERGE (s1)-[:BY]->(keep))
-      WITH keep, remove
-      OPTIONAL MATCH (s2)-[:HANDED_TO]->(remove)
+      WITH keep, alias
+      OPTIONAL MATCH (s2:Session)-[:HANDED_TO]->(alias)
       FOREACH (_ IN CASE WHEN s2 IS NOT NULL THEN [1] ELSE [] END | MERGE (s2)-[:HANDED_TO]->(keep))
-      WITH keep, remove
-      OPTIONAL MATCH (m)-[:INVOLVES]->(remove)
+      WITH keep, alias
+      OPTIONAL MATCH (m:Meeting)-[:INVOLVES]->(alias)
       FOREACH (_ IN CASE WHEN m IS NOT NULL THEN [1] ELSE [] END | MERGE (m)-[:INVOLVES]->(keep))
-      WITH keep, remove
-      OPTIONAL MATCH (a)-[:CONTRIBUTED_BY]->(remove)
+      WITH keep, alias
+      OPTIONAL MATCH (a:Artifact)-[:CONTRIBUTED_BY]->(alias)
       FOREACH (_ IN CASE WHEN a IS NOT NULL THEN [1] ELSE [] END | MERGE (a)-[:CONTRIBUTED_BY]->(keep))
-      WITH keep, remove
-      OPTIONAL MATCH (i)-[:CONDUCTED_BY]->(remove)
+      WITH keep, alias
+      OPTIONAL MATCH (i:Interview)-[:CONDUCTED_BY]->(alias)
       FOREACH (_ IN CASE WHEN i IS NOT NULL THEN [1] ELSE [] END | MERGE (i)-[:CONDUCTED_BY]->(keep))
-      WITH keep, remove
-      OPTIONAL MATCH (remove)-[:MEMBER_OF]->(o:Org)
+      WITH keep, alias
+      OPTIONAL MATCH (t:Todo)-[:BY]->(alias)
+      FOREACH (_ IN CASE WHEN t IS NOT NULL THEN [1] ELSE [] END | MERGE (t)-[:BY]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (mentionedArtifact:Artifact)-[:MENTIONS]->(alias)
+      FOREACH (_ IN CASE WHEN mentionedArtifact IS NOT NULL THEN [1] ELSE [] END | MERGE (mentionedArtifact)-[:MENTIONS]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (mentionedTodo:Todo)-[:MENTIONS]->(alias)
+      FOREACH (_ IN CASE WHEN mentionedTodo IS NOT NULL THEN [1] ELSE [] END | MERGE (mentionedTodo)-[:MENTIONS]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (q:Quest)-[:STARTED_BY]->(alias)
+      FOREACH (_ IN CASE WHEN q IS NOT NULL THEN [1] ELSE [] END | MERGE (q)-[:STARTED_BY]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (askedBy:QuestionSet)-[:ASKED_BY]->(alias)
+      FOREACH (_ IN CASE WHEN askedBy IS NOT NULL THEN [1] ELSE [] END | MERGE (askedBy)-[:ASKED_BY]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (askedTo:QuestionSet)-[:ASKED_TO]->(alias)
+      FOREACH (_ IN CASE WHEN askedTo IS NOT NULL THEN [1] ELSE [] END | MERGE (askedTo)-[:ASKED_TO]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (tu:TelegramUser)-[:IDENTIFIES]->(alias)
+      FOREACH (_ IN CASE WHEN tu IS NOT NULL THEN [1] ELSE [] END | MERGE (tu)-[:IDENTIFIES]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (reported:Issue)-[:REPORTED_BY]->(alias)
+      FOREACH (_ IN CASE WHEN reported IS NOT NULL THEN [1] ELSE [] END | MERGE (reported)-[:REPORTED_BY]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (initiated:Harvest)-[:INITIATED_BY]->(alias)
+      FOREACH (_ IN CASE WHEN initiated IS NOT NULL THEN [1] ELSE [] END | MERGE (initiated)-[:INITIATED_BY]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (withPerson:HarvestSession)-[:WITH]->(alias)
+      FOREACH (_ IN CASE WHEN withPerson IS NOT NULL THEN [1] ELSE [] END | MERGE (withPerson)-[:WITH]->(keep))
+      WITH keep, alias
+      OPTIONAL MATCH (alias)-[:SENT_EMISSARY]->(emissary:Emissary)
+      FOREACH (_ IN CASE WHEN emissary IS NOT NULL THEN [1] ELSE [] END | MERGE (keep)-[:SENT_EMISSARY]->(emissary))
+      WITH keep, alias
+      OPTIONAL MATCH (alias)-[:MEMBER_OF]->(o:Org)
       FOREACH (_ IN CASE WHEN o IS NOT NULL THEN [1] ELSE [] END | MERGE (keep)-[:MEMBER_OF]->(o))
-      WITH keep, remove
-      DETACH DELETE remove
+      WITH keep, alias
+      MERGE (alias)-[:ALIAS_OF]->(keep)
+      SET alias.kind = 'identity_alias',
+          alias.canonicalPersonId = keep.personId,
+          alias.identityStatus = 'alias'
       RETURN keep.name AS name, keep.github AS github, keep.previousNames AS aliases
-    " "$(jq -n --arg keep "$KEEP" --arg remove "$REMOVE" '{keep: $keep, remove: $remove}')"
+    " "$(jq -n --arg keep "$KEEP" --arg alias "$ALIAS" '{keep: $keep, alias: $alias}')"
     ;;
 
   claim-handoff)
@@ -176,15 +506,69 @@ case "$OP" in
     HO_SID="${2:?missing handoff-session-id}"
     CYPHER="
       MATCH (impl:Session {id: \$implSid}), (ho:Session {id: \$hoSid})
-      WHERE ho.handoffStatus IS NOT NULL
+      MATCH (impl)-[:BY]->(claimant:Person)
+      MATCH (ho)-[:HANDED_TO]->(claimant)
+      WHERE ho.handoffStatus IN ['pending','read','claimed']
       MERGE (impl)-[:IMPLEMENTS]->(ho)
-      RETURN impl.id AS implementor, ho.id AS handoff, ho.topic AS topic
+      WITH impl, ho, size([(ho)-[:HANDED_TO]->(:Person) | 1]) AS recipientCount
+      FOREACH (_ IN CASE WHEN recipientCount = 1 THEN [1] ELSE [] END |
+        SET ho.handoffStatus = 'claimed',
+            ho.handoffClaimedAt = coalesce(ho.handoffClaimedAt, datetime()),
+            ho.handoffUpdatedAt = datetime(),
+            ho.handoffLifecycleReason = 'implementation_claimed',
+            ho.handoffLifecycleVersion = 1)
+      RETURN impl.id AS implementor, ho.id AS handoff, ho.topic AS topic,
+             ho.handoffStatus AS status, recipientCount
     "
     PARAMS="$(jq -n --arg implSid "$IMPL_SID" --arg hoSid "$HO_SID" '{implSid: $implSid, hoSid: $hoSid}')"
     bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
     bash "$GS" query "$CYPHER" "$PARAMS"
     ;;
 
+  claim-handoff-nudge)
+    SID="${1:?missing handoff-session-id}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})-[:HANDED_TO]->(recipient:Person)
+      WHERE coalesce(s.handoffStatus, 'pending') IN ['pending','read','claimed']
+        AND coalesce(s.handoffLifecycleVersion, 0) >= 1
+        AND coalesce(s.handoffIntent, 'unclassified') IN ['action','feedback','fyi']
+        AND s.handoffNudgedAt IS NULL
+        AND (s.handoffNudgeClaimedAt IS NULL
+             OR s.handoffNudgeClaimedAt < datetime() - duration('PT1H'))
+      WITH s, collect(DISTINCT recipient.name) AS recipients
+      WHERE size(recipients) = 1
+      SET s.handoffNudgeClaimedAt = datetime(),
+          s.handoffNudgeStatus = 'claimed'
+      RETURN s.id AS id, s.topic AS topic, recipients
+    " "$(jq -n --arg sid "$SID" '{sid:$sid}')"
+    ;;
+
+  mark-handoff-nudged)
+    SID="${1:?missing handoff-session-id}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      WHERE s.handoffNudgeStatus = 'claimed' AND s.handoffNudgedAt IS NULL
+      SET s.handoffNudgedAt = datetime(),
+          s.handoffNudgeStatus = 'sent',
+          s.handoffUpdatedAt = datetime(),
+          s.handoffLifecycleReason = 'recipient_nudged',
+          s.handoffLifecycleVersion = 1
+      RETURN s.id AS id, s.handoffNudgeStatus AS status
+    " "$(jq -n --arg sid "$SID" '{sid:$sid}')"
+    ;;
+
+  release-handoff-nudge)
+    SID="${1:?missing handoff-session-id}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      WHERE s.handoffNudgeStatus = 'claimed' AND s.handoffNudgedAt IS NULL
+      SET s.handoffNudgeClaimedAt = null,
+          s.handoffNudgeStatus = 'failed',
+          s.handoffNudgeFailedAt = datetime()
+      RETURN s.id AS id, s.handoffNudgeStatus AS status
+    " "$(jq -n --arg sid "$SID" '{sid:$sid}')"
+    ;;
+
   create-pr)
     SID="${1:?missing session-id}"
     PR_NUM="${2:?missing pr-number}"
@@ -315,6 +699,292 @@ case "$OP" in
     fi
     ;;
 
+  open-handoffs)
+    USER="${1:?missing username}"
+    LIMIT="${2:-10}"
+    if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 25 ]; then
+      echo '{"error":"limit must be between 1 and 25"}'
+      exit 2
+    fi
+    bash "$GS" query "
+      MATCH (s:Session)-[:HANDED_TO]->(p:Person)
+      WHERE (
+        toLower(coalesce(p.name, '')) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)
+        OR toLower(coalesce(p.githubUsername, '')) = toLower(\$user)
+        OR any(alias IN coalesce(p.previousNames, [])
+               WHERE toLower(alias) = toLower(\$user))
+      )
+        AND coalesce(s.handoffStatus, 'pending')
+            IN ['pending','unread','read','claimed']
+      WITH DISTINCT s
+      OPTIONAL MATCH (s)-[:BY]->(author:Person)
+      WITH s, author,
+           CASE WHEN s.date IS NULL THEN null
+                ELSE duration.inDays(date(s.date), date()).days END AS ageDays
+      RETURN s.id AS id,
+             coalesce(s.topic, s.summary, s.branch) AS topic,
+             coalesce(author.name, s.author, 'unknown') AS author,
+             toString(s.date) AS date,
+             coalesce(s.handoffStatus, 'pending') AS status,
+             coalesce(s.handoffIntent, 'unclassified') AS intent,
+             ageDays,
+             CASE WHEN ageDays IS NULL THEN 'unknown'
+                  WHEN ageDays <= 14 THEN 'current'
+                  WHEN ageDays <= 30 THEN 'aging'
+                  ELSE 'stale' END AS freshness,
+             1 AS definitionVersion
+      ORDER BY s.date DESC, s.id
+      LIMIT \$limit
+    " "$(jq -n --arg user "$USER" --argjson limit "$LIMIT" '{user: $user, limit: $limit}')"
+    ;;
+
+  pending-questions)
+    USER="${1:?missing username}"
+    LIMIT="${2:-10}"
+    if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 25 ]; then
+      echo '{"error":"limit must be between 1 and 25"}'
+      exit 2
+    fi
+    bash "$GS" query "
+      MATCH (qs:QuestionSet)-[:ASKED_TO]->(p:Person)
+      WHERE (
+        toLower(coalesce(p.name, '')) = toLower(\$user)
+        OR toLower(coalesce(p.github, '')) = toLower(\$user)
+        OR toLower(coalesce(p.githubUsername, '')) = toLower(\$user)
+        OR any(alias IN coalesce(p.previousNames, [])
+               WHERE toLower(alias) = toLower(\$user))
+      )
+        AND coalesce(qs.status, 'pending') IN ['pending','active']
+      WITH DISTINCT qs
+      OPTIONAL MATCH (q:Question)-[:PART_OF]->(qs)
+      OPTIONAL MATCH (qs)-[:ASKED_BY]->(asker:Person)
+      WITH qs, asker, count(DISTINCT q) AS questions,
+           CASE WHEN qs.created IS NULL THEN null
+                ELSE duration.inDays(date(datetime(qs.created)), date()).days END AS ageDays
+      RETURN qs.id AS id,
+             qs.topic AS topic,
+             coalesce(asker.name, qs.askedBy, qs.from, 'unknown') AS askedBy,
+             questions,
+             toString(qs.created) AS created,
+             ageDays,
+             CASE WHEN ageDays IS NULL THEN 'unknown'
+                  WHEN ageDays <= 14 THEN 'current'
+                  WHEN ageDays <= 30 THEN 'aging'
+                  ELSE 'stale-open' END AS freshness,
+             1 AS definitionVersion
+      ORDER BY qs.created DESC, qs.id
+      LIMIT \$limit
+    " "$(jq -n --arg user "$USER" --argjson limit "$LIMIT" '{user: $user, limit: $limit}')"
+    ;;
+
+  lineage)
+    QUERY="${1:?missing topic}"
+    LIMIT="${2:-10}"
+    if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 15 ]; then
+      echo '{"error":"limit must be between 1 and 15"}'
+      exit 2
+    fi
+    GRAPH_RAW="$(bash "$GS" query "
+      MATCH (s:Session)
+      WHERE toLower(coalesce(s.topic, '')) CONTAINS toLower(\$query)
+         OR toLower(coalesce(s.summary, '')) CONTAINS toLower(\$query)
+         OR toLower(coalesce(s.branch, '')) CONTAINS toLower(\$query)
+      OPTIONAL MATCH (s)-[:BY]->(author:Person)
+      OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+      OPTIONAL MATCH (implementation:Session)-[:IMPLEMENTS]->(s)
+      OPTIONAL MATCH (implementation)-[:BY]->(implementer:Person)
+      OPTIONAL MATCH (s)-[:IMPLEMENTS]->(prior:Session)
+      OPTIONAL MATCH (prior)-[:BY]->(priorAuthor:Person)
+      OPTIONAL MATCH (s)-[:PRODUCED]->(pr:PR)
+      OPTIONAL MATCH (implementation)-[:PRODUCED]->(implementationPr:PR)
+      WITH s, author,
+           collect(DISTINCT coalesce(recipient.name, recipient.github)) AS recipients,
+           collect(DISTINCT CASE WHEN implementation IS NULL THEN null ELSE {
+             id: implementation.id,
+             topic: implementation.topic,
+             summary: implementation.summary,
+             branch: implementation.branch,
+             date: toString(implementation.date),
+             evidencePath: CASE
+               WHEN implementation.filePath IS NULL THEN null
+               WHEN implementation.filePath STARTS WITH 'memory/' THEN implementation.filePath
+               ELSE 'memory/' + implementation.filePath END,
+             implementedBy: coalesce(implementer.name, implementer.github)
+           } END) AS implementations,
+           collect(DISTINCT CASE WHEN prior IS NULL THEN null ELSE {
+             id: prior.id,
+             topic: prior.topic,
+             summary: prior.summary,
+             branch: prior.branch,
+             date: toString(prior.date),
+             evidencePath: CASE
+               WHEN prior.filePath IS NULL THEN null
+               WHEN prior.filePath STARTS WITH 'memory/' THEN prior.filePath
+               ELSE 'memory/' + prior.filePath END,
+             author: coalesce(priorAuthor.name, priorAuthor.github)
+           } END) AS implements,
+           collect(DISTINCT CASE WHEN pr IS NULL THEN null ELSE {
+             number: pr.number, repo: pr.repo, title: pr.title,
+             status: pr.status, mergedAt: toString(pr.mergedAt)
+           } END)
+           + collect(DISTINCT CASE WHEN implementationPr IS NULL THEN null ELSE {
+             number: implementationPr.number, repo: implementationPr.repo,
+             title: implementationPr.title, status: implementationPr.status,
+             mergedAt: toString(implementationPr.mergedAt)
+           } END) AS prs
+      RETURN s.id AS sessionId,
+             s.topic AS topic,
+             s.summary AS summary,
+             s.branch AS branch,
+             toString(s.date) AS date,
+             CASE WHEN s.filePath IS NULL THEN null
+                  WHEN s.filePath STARTS WITH 'memory/' THEN s.filePath
+                  ELSE 'memory/' + s.filePath END AS evidencePath,
+             coalesce(author.name, author.github, s.author, 'unknown') AS author,
+             recipients[0..20] AS recipients,
+             implementations[0..10] AS implementations,
+             implements[0..10] AS implements,
+             prs[0..10] AS prs
+      ORDER BY s.date DESC, s.id
+      LIMIT \$limit
+    " "$(jq -n --arg query "$QUERY" --argjson limit "$LIMIT" '{query:$query,limit:$limit}')")"
+    FILES_RAW="$(memory_file_candidates "$QUERY" "$LIMIT" \
+      "$SCRIPT_DIR/memory/handoffs" \
+      "$SCRIPT_DIR/memory/wraps" \
+      "$SCRIPT_DIR/memory/sessions")"
+    jq -n \
+      --arg query "$QUERY" \
+      --argjson limit "$LIMIT" \
+      --argjson graph "$GRAPH_RAW" \
+      --argjson files "$FILES_RAW" '
+      ($graph.values // [] | map({
+        sessionId: .[0], topic: .[1], summary: .[2], branch: .[3],
+        date: .[4], evidencePath: .[5], author: .[6],
+        recipients: (.[7] // []), implementations: (.[8] // []),
+        implements: (.[9] // []), prs: (.[10] // [])
+      })) as $matches
+      | ($matches | map(.evidencePath) | map(select(. != null)) | unique) as $graphPaths
+      | ($files | map(.evidencePath) | unique) as $filePaths
+      | ($filePaths - $graphPaths) as $unprojected
+      | {
+          schema: "egregore.graph-read/v1",
+          operation: "lineage",
+          definitionVersion: 1,
+          query: $query,
+          limit: $limit,
+          coverage:
+            (if ($graphPaths | length) == 0 then
+               (if ($filePaths | length) == 0 then "none" else "filesystem-only" end)
+             elif ($unprojected | length) > 0 then "partial"
+             else "complete" end),
+          graphMatches: $matches,
+          fileCandidates:
+            ($files | map(
+              . as $candidate
+              | . + {
+                projection:
+                  (if ($graphPaths | index($candidate.evidencePath)) != null
+                   then "projected" else "unprojected" end)
+              }
+            )),
+          unprojectedPaths: $unprojected
+        }
+    '
+    ;;
+
+  meeting-history)
+    QUERY="${1:?missing company, person, or topic}"
+    LIMIT="${2:-10}"
+    if ! [[ "$LIMIT" =~ ^[0-9]+$ ]] || [ "$LIMIT" -lt 1 ] || [ "$LIMIT" -gt 15 ]; then
+      echo '{"error":"limit must be between 1 and 15"}'
+      exit 2
+    fi
+    QUERY_TERMS="$(meaningful_query_terms "$QUERY")"
+    GRAPH_RAW="$(bash "$GS" query "
+      MATCH (m:Meeting)
+      OPTIONAL MATCH (m)-[:INVOLVES|CONDUCTED_BY]->(participant:Person)
+      WITH m, collect(DISTINCT participant) AS participants
+      WITH m, participants,
+           [term IN \$terms WHERE
+             toLower(coalesce(m.title, '')) CONTAINS term
+             OR toLower(coalesce(m.name, '')) CONTAINS term
+             OR toLower(coalesce(m.id, '')) CONTAINS term
+             OR any(p IN participants WHERE
+                  toLower(coalesce(p.name, '')) CONTAINS term
+                  OR toLower(coalesce(p.github, '')) CONTAINS term)
+           ] AS matchedTerms
+      WHERE size(matchedTerms) > 0
+      OPTIONAL MATCH (artifact:Artifact)-[:FROM_MEETING]->(m)
+      RETURN m.id AS meetingId,
+             coalesce(m.title, m.name, m.id) AS title,
+             toString(m.date) AS date,
+             CASE WHEN m.filePath IS NULL THEN null
+                  WHEN m.filePath STARTS WITH 'memory/' THEN m.filePath
+                  ELSE 'memory/' + m.filePath END AS evidencePath,
+             ([p IN participants | coalesce(p.name, p.github)])[0..20] AS participants,
+             (collect(DISTINCT CASE WHEN artifact IS NULL THEN null ELSE {
+               id: artifact.id,
+               type: artifact.type,
+               title: artifact.title,
+               summary: artifact.summary,
+               evidencePath: CASE
+                 WHEN artifact.filePath IS NULL THEN null
+                 WHEN artifact.filePath STARTS WITH 'memory/' THEN artifact.filePath
+                 ELSE 'memory/' + artifact.filePath END
+             } END))[0..10] AS derivedKnowledge,
+             coalesce(m.verificationStatus, 'legacy') AS verificationStatus,
+             m.ingestManifestId AS ingestManifestId,
+             matchedTerms,
+             size(matchedTerms) AS matchScore
+      ORDER BY matchScore DESC, date ASC, meetingId
+      LIMIT \$limit
+    " "$(jq -n --arg query "$QUERY" --argjson terms "$QUERY_TERMS" --argjson limit "$LIMIT" \
+      '{query:$query,terms:$terms,limit:$limit}')")"
+    FILES_RAW="$(memory_file_candidates_for_terms \
+      "$QUERY_TERMS" "$LIMIT" "$SCRIPT_DIR/memory/meetings")"
+    jq -n \
+      --arg query "$QUERY" \
+      --argjson queryTerms "$QUERY_TERMS" \
+      --argjson limit "$LIMIT" \
+      --argjson graph "$GRAPH_RAW" \
+      --argjson files "$FILES_RAW" '
+      ($graph.values // [] | map({
+        meetingId: .[0], title: .[1], date: .[2], evidencePath: .[3],
+        participants: (.[4] // []), derivedKnowledge: (.[5] // []),
+        verificationStatus: .[6], ingestManifestId: .[7],
+        matchedTerms: (.[8] // []), matchScore: (.[9] // 0)
+      })) as $meetings
+      | ($meetings | map(.evidencePath) | map(select(. != null)) | unique) as $graphPaths
+      | ($files | map(.evidencePath) | unique) as $filePaths
+      | ($filePaths - $graphPaths) as $unprojected
+      | {
+          schema: "egregore.graph-read/v1",
+          operation: "meeting-history",
+          definitionVersion: 1,
+          query: $query,
+          queryTerms: $queryTerms,
+          limit: $limit,
+          coverage:
+            (if ($graphPaths | length) == 0 then
+               (if ($filePaths | length) == 0 then "none" else "filesystem-only" end)
+             elif ($unprojected | length) > 0 then "partial"
+             else "complete" end),
+          graphMeetings: $meetings,
+          fileCandidates:
+            ($files | map(
+              . as $candidate
+              | . + {
+                projection:
+                  (if ($graphPaths | index($candidate.evidencePath)) != null
+                   then "projected" else "unprojected" end)
+              }
+            )),
+          unprojectedPaths: $unprojected
+        }
+    '
+    ;;
+
   wal-status)
     bash "$SCRIPT_DIR/bin/graph-wal.sh" status
     ;;
@@ -424,7 +1094,7 @@ case "$OP" in
     ;;
 
   *)
-    echo '{"error":"unknown operation: '"$OP"'","operations":["mark-read","mark-done","answer-question","resolve-handoffs","set-topic","record-focus","merge-person","claim-handoff","check-implements","create-pr","update-pr","my-merged-prs","my-implemented-handoffs","wal-status","create-harvest","create-harvest-session","record-harvest-turn","complete-harvest"]}'
+    echo '{"error":"unknown operation: '"$OP"'","operations":["catalog","mark-read","mark-done","mark-expired","reopen-handoff","answer-question","resolve-handoffs","set-topic","record-focus","merge-person","claim-handoff","claim-handoff-nudge","mark-handoff-nudged","release-handoff-nudge","check-implements","create-pr","update-pr","my-merged-prs","my-implemented-handoffs","open-handoffs","pending-questions","lineage","meeting-history","wal-status","create-harvest","create-harvest-session","record-harvest-turn","complete-harvest"]}'
     exit 1
     ;;