@forwardimpact/outpost 3.5.1 → 3.7.0

package/templates/.claude/skills/person-lookup/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: person-lookup
+description: Look up ANY person in the corporate directory from free-text input (an email address, or a first / last / full name) and return their record — real name, title, department, company, email, employee ID, office, and manager. Searches the Global Catalog forest-wide via LDAP, authenticated with the existing Kerberos ticket. Use when the user asks "who is X", needs someone's title / department / manager / email, or wants to disambiguate a name. For the *current* user's own identity, use the sibling `person-identify` skill instead.
+---
+
+# Person Lookup
+
+Resolve **any** person in the corporate Active Directory from natural-language
+input — an email, a login, or any part of a name. The sibling of
+`person-identify`, but aimed at *other* people: it searches the **Global
+Catalog** (forest-wide), handles multiple matches, flags external contacts and
+vendor accounts, and — unlike `person-identify` — never writes the identity
+cache. It's a read-only, throwaway lookup.
+
+## Trigger
+
+- The user asks "who is <name>", or for someone's title, department, manager,
+  email, or employee ID.
+- A name is ambiguous and needs disambiguating against the directory.
+- Another skill needs to resolve a person who is **not** the current user.
+
+For the current user's own record (and to populate the identity cache that other
+skills read), use `person-identify` instead.
+
+## Prerequisites
+
+- A valid **Kerberos ticket** (`klist` shows a principal). If absent:
+  `kinit <user>@<REALM>`.
+- Network reachability to a domain controller (on-site or VPN).
+- `ldapsearch` and `dig` — both ship with macOS; nothing to install.
+
+Nothing is hardcoded: the realm and a domain controller are derived at runtime
+from the ticket and DNS. The bind uses SASL/GSSAPI against the existing ticket —
+no password is ever entered.
+
+## Usage
+
+```bash
+bash .claude/skills/person-lookup/scripts/lookup.sh "Jane Doe"
+bash .claude/skills/person-lookup/scripts/lookup.sh "jane.doe@example.com"
+```
+
+The argument is free text: an email, a full name, or just a surname.
+
+## How it works
+
+1. **Derive a domain controller** from the Kerberos principal's realm via DNS
+   SRV (same bootstrap as `person-identify`).
+2. **Search the Global Catalog** (`ldap://$dc:3268`, base `""`). The GC spans
+   *every* domain in the forest, so a colleague in another region is found from
+   your own ticket — a plain domain-scoped search would miss them. It also
+   returns the common attributes (title, department, mail, manager), so one
+   query is enough.
+3. **Match with ANR** (Ambiguous Name Resolution): the `(anr=<input>)` filter
+   matches an email, a login, or any name part in one shot. If ANR finds
+   nothing, fall back to a substring search on `mail` / `displayName` /
+   `proxyAddresses`.
+4. **Resolve per match.** For a single hit, print the full record and resolve
+   the `manager` DN to a name. For several hits, print a compact
+   disambiguation list and suggest narrowing by email.
+
+## Output
+
+| Field | Source attribute |
+| --- | --- |
+| Name | `displayName` (fallback `cn`) |
+| Type | `objectClass` + OU — **Employee**, **Contact (external)**, or **User (external / vendor)** |
+| Email | `mail` |
+| Title | `title` |
+| Department | `department` |
+| Company | `company` |
+| Employee ID | `employeeID` |
+| Phone / Office | `telephoneNumber` / `physicalDeliveryOfficeName` |
+| Manager | `manager` (DN → resolved to a name) |
+| DN | distinguished name (region + OU, useful for disambiguation) |
+
+## Notes
+
+- **Multiple matches are normal.** A common name, or a person who also has an
+  external **Contact** object (e.g. a vendor email alias), returns several
+  entries. The **Type** column distinguishes an internal **Employee** from an
+  external **Contact** (standard `objectClass=contact`). Some directories also
+  park external/vendor *user* accounts under a dedicated OU; set
+  `VENDOR_OU_PATTERN` at the top of `scripts/lookup.sh` to your directory's OU
+  substring (e.g. `OU=Contractors`) to flag those too. It is empty by default,
+  since the OU convention is organization-specific. Narrow with an email for an
+  exact hit.
+- **Silent partial results.** Under load the directory occasionally returns an
+  entry's DN with no attributes (exit 0, no error). Every attribute fetch retries
+  with backoff, so a throttled response never masquerades as a person with a
+  blank title or email.
+- **No cache.** This skill prints and exits. It never touches
+  `~/.cache/fit/outpost/state/identity.md` — that file is owned solely by
+  `person-identify`.
+- **Ethics.** This reads objective, work-relevant directory data only, in line
+  with the knowledge base's integrity rules. It is not a tool for building
+  dossiers.

package/templates/.claude/skills/person-lookup/scripts/lookup.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# person-lookup: resolve ANY person in the corporate directory from free-text
+# input (an email address, or a first / last / full name) and print their
+# directory record(s).
+#
+# Sibling to `person-identify`, but for *other* people, not the current user:
+#   - Searches the Global Catalog (port 3268, base "") so it reaches EVERY
+#     domain in the forest from a single ticket — colleagues in other regions
+#     are found, not just your own domain.
+#   - Uses Active Directory ANR (Ambiguous Name Resolution), so one filter
+#     matches an email, a login, or any part of a name.
+#   - Handles 0, 1, or many matches, and flags external Contacts / vendor
+#     accounts so an internal employee is never confused with an outside one.
+#   - NEVER writes the identity cache — this is a throwaway lookup.
+#
+# Auth uses SASL/GSSAPI against the existing Kerberos ticket — no password.
+#
+# Robustness note: under load the directory intermittently returns an entry's
+# DN with NO attributes (exit 0, no error). Every attribute fetch below retries
+# with backoff so a throttled response never looks like "this person has no
+# title / email".
+set -u
+
+# Org-specific: substring of the DN's OU that marks external/vendor *user*
+# accounts (external Contact objects are detected generically via objectClass).
+# Empty by default — set it to your directory's convention, e.g. "OU=Contractors"
+# or "OU=External", to label those accounts as "User (external / vendor)".
+VENDOR_OU_PATTERN=""
+
+QUERY="$*"
+if [ -z "$QUERY" ]; then
+  echo "Usage: lookup.sh <email | name>     e.g.  lookup.sh \"Jane Doe\"" >&2
+  exit 2
+fi
+
+# 1. Derive the realm and a reachable domain controller from the Kerberos ticket.
+princ=$(klist 2>/dev/null | sed -n 's/.*[Pp]rincipal: *//p' | head -1)
+if [ -z "$princ" ]; then
+  echo "No Kerberos ticket found. Get one first, e.g.:  kinit <user>@<REALM>" >&2
+  exit 1
+fi
+realm=${princ#*@}
+dom=$(printf '%s' "$realm" | tr '[:upper:]' '[:lower:]')
+dc=$(dig +short SRV "_ldap._tcp.dc._msdcs.$dom" | awk 'NR==1{print $4}' | sed 's/\.$//')
+[ -z "$dc" ] && dc=$(dig +short SRV "_ldap._tcp.$dom" | awk 'NR==1{print $4}' | sed 's/\.$//')
+if [ -z "$dc" ]; then
+  echo "Could not find a domain controller for $dom via DNS SRV." >&2
+  exit 1
+fi
+
+# Global Catalog: forest-wide, base "" spans every domain.
+GC="ldap://$dc:3268"
+ATTRS="displayName givenName sn company title department employeeID mail telephoneNumber physicalDeliveryOfficeName objectClass manager"
+MAX_SHOW=12   # cap detailed output for very broad name matches
+
+# Pull one attribute out of an LDIF record (passed as $2), decoding base64 (::).
+field() { # $1=attr  $2=record
+  local attr="$1" line
+  line=$(printf '%s\n' "$2" | grep -m1 -E "^$attr:: ?|^$attr: ") || return 0
+  case "$line" in
+    "$attr:: "*) printf '%s' "${line#"$attr":: }" | base64 -D 2>/dev/null ;;
+    "$attr: "*)  printf '%s' "${line#"$attr": }" ;;
+  esac
+}
+
+# List matching DNs for a filter (no attributes requested → reliable under load).
+dns_for() { # $1=filter
+  ldapsearch -Y GSSAPI -LLL -o ldif-wrap=no -H "$GC" -b "" "$1" 1.1 2>/dev/null \
+    | sed -n 's/^dn: //p'
+}
+
+# Fetch one entry's attributes by DN, retrying past the silent DN-only response.
+fetch() { # $1=dn
+  local dn="$1" out tries=0
+  while [ "$tries" -lt 4 ]; do
+    out=$(ldapsearch -Y GSSAPI -LLL -o ldif-wrap=no -H "$GC" -b "$dn" -s base \
+            "(objectClass=*)" $ATTRS 2>/dev/null | grep -vE '^# ')
+    printf '%s\n' "$out" | grep -qE '^displayName:' && break
+    tries=$((tries + 1)); sleep "$tries"
+  done
+  printf '%s\n' "$out"
+}
+
+# Resolve a manager (or any) DN to a display name.
+name_of_dn() { # $1=dn
+  [ -z "$1" ] && return 0
+  field displayName "$(fetch "$1")"
+}
+
+# Classify an entry: internal employee, external contact, or vendor account.
+kind_of() { # $1=record  $2=dn
+  local oc; oc=$(printf '%s\n' "$1" | grep -i '^objectClass:' | tr 'A-Z' 'a-z')
+  if printf '%s' "$oc" | grep -q 'contact'; then
+    echo "Contact (external)"
+  elif [ -n "$VENDOR_OU_PATTERN" ] && printf '%s' "$2" | grep -qiE ",$VENDOR_OU_PATTERN"; then
+    echo "User (external / vendor)"
+  else
+    echo "Employee"
+  fi
+}
+
+# 2. Primary search (ANR), then a substring fallback if it finds nothing.
+#    (Portable array fill — macOS ships bash 3.2, which has no `mapfile`.)
+read_dns() { # $1=filter  -> populates global DNS array
+  DNS=()
+  local line
+  while IFS= read -r line; do
+    [ -n "$line" ] && DNS+=("$line")
+  done < <(dns_for "$1")
+}
+read_dns "(anr=$QUERY)"
+if [ "${#DNS[@]}" -eq 0 ]; then
+  read_dns "(|(mail=*$QUERY*)(displayName=*$QUERY*)(proxyAddresses=*$QUERY*))"
+fi
+
+if [ "${#DNS[@]}" -eq 0 ]; then
+  echo "No directory match for: $QUERY"
+  exit 0
+fi
+
+# 3a. Exactly one match → full record, with the manager resolved to a name.
+if [ "${#DNS[@]}" -eq 1 ]; then
+  rec=$(fetch "${DNS[0]}")
+  mgr=$(name_of_dn "$(field manager "$rec")")
+  echo "# $(field displayName "$rec")"
+  echo
+  echo "- **Type:** $(kind_of "$rec" "${DNS[0]}")"
+  echo "- **Email:** $(field mail "$rec")"
+  echo "- **Title:** $(field title "$rec")"
+  echo "- **Department:** $(field department "$rec")"
+  echo "- **Company:** $(field company "$rec")"
+  echo "- **Employee ID:** $(field employeeID "$rec")"
+  echo "- **Phone:** $(field telephoneNumber "$rec")"
+  echo "- **Office:** $(field physicalDeliveryOfficeName "$rec")"
+  [ -n "$mgr" ] && echo "- **Manager:** $mgr"
+  echo "- **DN:** ${DNS[0]}"
+  exit 0
+fi
+
+# 3b. Several matches → a compact disambiguation list (no per-row manager call).
+echo "${#DNS[@]} matches for \"$QUERY\" — narrow with an email for an exact hit:"
+echo
+shown=0
+for dn in "${DNS[@]}"; do
+  if [ "$shown" -ge "$MAX_SHOW" ]; then
+    echo
+    echo "_… and $(( ${#DNS[@]} - MAX_SHOW )) more. Refine the query._"
+    break
+  fi
+  rec=$(fetch "$dn")
+  name=$(field displayName "$rec"); [ -z "$name" ] && name=$(field cn "$rec")
+  printf -- '- **%s** — %s\n' "$name" "$(kind_of "$rec" "$dn")"
+  printf -- '    - %s · %s · %s\n' \
+    "$(field mail "$rec")" "$(field title "$rec")" "$(field department "$rec")"
+  printf -- '    - %s\n' "$dn"
+  shown=$((shown + 1))
+done

package/templates/.claude/skills/req-track/SKILL.md

@@ -20,7 +20,7 @@ pipeline from scattered email threads.
 
 - Synced email data in `~/.cache/fit/outpost/apple_mail/` (from
   `sync-apple-mail`).
-- User identity — run the `identify-user` skill to populate
+- User identity — run the `person-identify` skill to populate
   `~/.cache/fit/outpost/state/identity.md`.
 
 ## Inputs
@@ -33,7 +33,7 @@ pipeline from scattered email threads.
 - `~/.cache/fit/outpost/state/graph_processed` — processed-file index (shared
   with `extract-entities`).
 - `~/.cache/fit/outpost/state/identity.md` — user identity for self-exclusion
-  (written by the `identify-user` skill).
+  (written by the `person-identify` skill).
 
 ## Outputs
 
@@ -71,7 +71,7 @@ Process **10 files per run**.
 ### 1. Load context and pick the batch
 
 Read the user's name, email, and domain from
-`~/.cache/fit/outpost/state/identity.md` (run the `identify-user` skill first if
+`~/.cache/fit/outpost/state/identity.md` (run the `person-identify` skill first if
 it is missing or stale). List new or changed source files:
 
 ```bash

package/templates/.claude/skills/req-workday/SKILL.md

@@ -27,7 +27,7 @@ integrate with the `req-track` pipeline format.
 - A Workday requisition export accessible on the filesystem.
 - `read-excel-file` package installed:
   `bun pm ls read-excel-file 2>/dev/null || bun install read-excel-file`.
-- User identity — run the `identify-user` skill to populate
+- User identity — run the `person-identify` skill to populate
   `~/.cache/fit/outpost/state/identity.md`.
 
 ## Inputs
@@ -66,7 +66,7 @@ Process **10 candidates per run**.
 ### 1. Set up
 
 Read the user's identity from `~/.cache/fit/outpost/state/identity.md` (run the
-`identify-user` skill first if it is missing or stale). Confirm the XLSX path.
+`person-identify` skill first if it is missing or stale). Confirm the XLSX path.
 Ensure the parser dependency is installed:
 
 ```bash

package/templates/.claude/skills/upstream-instructions/SKILL.md

@@ -24,15 +24,15 @@ monorepo. "Instructions" means all three surfaces, treated equally:
 
 - A working Outpost installation with `CLAUDE.md`, `.claude/agents/`, and
   `.claude/skills/`.
-- Git available for change detection.
 
 ## Inputs
 
 - `CLAUDE.md` — root installation instructions.
 - `.claude/agents/*.md` — agent profiles.
 - `.claude/skills/*/SKILL.md` and reference files — skills.
-- `CHANGELOG.md` (root) — the existing changelog, for the last documented date.
-- Git history and working tree — change detection.
+- `CHANGELOG.md` (root) — the existing changelog, for what's already recorded.
+- The changes made in the current working session — the source of truth for what
+  changed, since the KB lives on a synced filesystem and is not version-controlled.
 
 ## Outputs
 
@@ -49,8 +49,7 @@ monorepo. "Instructions" means all three surfaces, treated equally:
       "updated CLAUDE.md" / "fixed stuff").
 - [ ] New skills/agents include a brief description of their purpose; removed
       ones explain why.
-- [ ] Dates come from git history (or the date the change was made for
-      uncommitted edits), not guessed.
+- [ ] Dates are the date the change was made, not guessed.
 - [ ] No duplicate entries for the same change.
 
 </do_confirm_checklist>
@@ -65,18 +64,15 @@ head -20 CHANGELOG.md 2>/dev/null   # newest date already recorded, if any
 
 ### 2. Identify changed instructions
 
-Detect changes across all three surfaces — committed and uncommitted:
+Knowledge bases live on a synced filesystem, not in Git, so there is no commit
+history to diff. Identify what changed from the work just done **this session**:
+recall every edit, addition, removal, and rename made to `CLAUDE.md`,
+`.claude/agents/`, and `.claude/skills/` during the current conversation, and
+list them per surface.
 
-```bash
-# Committed changes since the last documented date (or all history)
-git log --after="<last-entry-date>" --name-status -- \
-  CLAUDE.md '.claude/agents/' '.claude/skills/'
-
-# Uncommitted working-tree changes (common in a live installation)
-git status --short -- CLAUDE.md '.claude/agents/' '.claude/skills/'
-```
-
-If no `CHANGELOG.md` exists yet, consider all changes since the initial commit.
+Use `CHANGELOG.md` only to see what's already recorded so you don't duplicate an
+existing entry. If something was clearly changed but you can't reconstruct what
+or why from the session, flag it as needing review rather than guessing.
 
 ### 3. Classify each change
 
@@ -95,13 +91,8 @@ If no `CHANGELOG.md` exists yet, consider all changes since the initial commit.
 
 A single change often spans surfaces (e.g. a KB-structure change touching
 `CLAUDE.md`, several agents, and several skills) — record it as **one entry**
-whose Scope lists every surface touched. Diff to confirm the actual change:
-
-```bash
-git diff <commit> -- CLAUDE.md
-git diff <commit> -- '.claude/agents/<agent>.md'
-git diff <commit> -- '.claude/skills/<skill>/'
-```
+whose Scope lists every surface touched. Re-read the affected files to confirm
+the change landed as intended before describing it.
 
 ### 4. Describe each change
 

package/templates/CLAUDE.md

@@ -113,7 +113,7 @@ knowledge-graph maintenance, recruitment, and communication.
 
 The current user's identity is cached at
 `~/.cache/fit/outpost/state/identity.md` — read it directly. If missing or stale,
-run the `identify-user` skill to refresh it from the corporate directory.
+run the `person-identify` skill to refresh it from the corporate directory.
 
 ## Working Outside This Directory