Skip to content

me2resh/apexyard / .claude/skills/orbit

Run the opt-in ORBIT planning lifecycle for one managed project without replacing ApexYard governance.

FileKindSize
SKILL.mdskill md27.5 KB
lib/handoff-preflight.shexecutablescript9.2 KB
lib/record-check.shexecutablescript3.5 KB
lib/records-lint.shexecutablescript14.5 KB
lib/refresh-slice-record.shexecutablescript3.4 KB
lib/resolve-project-repo.shexecutablescript2.1 KB
lib/slice-pr-lint.shscript10.6 KB
lib/status-live.shexecutablescript3.4 KB
lib/warn-criterion-shape.shexecutablescript3.3 KB
lib/warn-uncovered-outcomes.shexecutablescript8.2 KB
tests/_lib-fixtures.shexecutablescript8.0 KB
tests/_lib-slice-fixtures.shscript1.8 KB
tests/smoke.shexecutablescript1.3 KB
tests/test_criterion_shape.shexecutablescript3.5 KB
tests/test_handoff_allows_duplicate_prefix_match.shexecutablescript1.9 KB
tests/test_handoff_preflight_happy_path.shexecutablescript1.9 KB
tests/test_handoff_refusal_cli_absent.shexecutablescript1.6 KB
tests/test_handoff_refusal_duplicate_search_fails.shexecutablescript1.5 KB
tests/test_handoff_refusal_duplicate_search_truncated.shexecutablescript2.1 KB
tests/test_handoff_refusal_duplicate_slice.shexecutablescript1.8 KB
tests/test_handoff_refusal_leak_scrub.shexecutablescript4.8 KB
tests/test_handoff_refusal_missing_option_value.shexecutablescript2.4 KB
tests/test_handoff_refusal_slice_id_double_quote.shexecutablescript2.9 KB
tests/test_handoff_refusal_slice_id_newline.shexecutablescript2.8 KB
tests/test_handoff_refusal_validate_fails.shexecutablescript1.4 KB
tests/test_record_check_blank_line.shexecutablescript4.1 KB
tests/test_record_check_change_only.shexecutablescript3.7 KB
tests/test_records_lint_changed_fields.shexecutablescript4.8 KB
tests/test_records_lint_faults.shexecutablescript6.1 KB
tests/test_records_lint_slice_evidence.shscript1.2 KB
tests/test_records_lint_slice_merge_base_drift.shexecutablescript7.2 KB
tests/test_records_lint_slice_provenance.shscript532 B
tests/test_records_lint_slice_scope.shscript1.8 KB
tests/test_records_lint_slice_warn.shscript324 B
tests/test_records_lint_upstream_skip.shscript3.0 KB
tests/test_refresh_slice_record.shscript3.4 KB
tests/test_resolve_project_repo_registry.shexecutablescript4.2 KB
tests/test_slice_pr_proposal.shscript2.9 KB
tests/test_slice_ticket_workflow.shscript1.4 KB
tests/test_status_live_squash_commit.shscript858 B
tests/test_status_live_writes_nothing.shexecutablescript1.9 KB
tests/test_uncovered_outcomes.shscript11.0 KB

lib/records-lint.sh

View on GitHub
#!/usr/bin/env bash
# The slice helper reads the option variables.
# shellcheck disable=SC2034

# records-lint.sh — lint ORBIT records before a records PR (AgDR-0225, ac8-1).
#
# Runs the checks in order and stops on the first fault:
#   1. orbit validate --all
#   2. leak scrub (check-private-refs-runtime.sh) on record text
#   3. sentence check: at most 25 words in a sentence of a record text field
#   4. "Missing: ... Next:" rule for a non-achieved explanation
#   5. local-path check
#   6. Plan interview: six dated operator answers in the Plan notes
#   7. Slice PR: compare scope with the newest base record.
#   8. Slice PR: raised statuses need evidence from changed paths.
#   9. Slice PR: check the PR number and merge-base observation.
# A slice PR without a Reconciliation produces a warning.
# Checks 2 to 6 read the record files changed against --base (default
# origin/dev), or every record file with --all.
# By default, checks 3 and 4 read only the text that changed against the merge
# base. A JSON record is compared field by field. A notes file is compared line
# by line. A new file counts as fully changed. A file whose only change is
# "basedOn" has no changed text, so it gets the validate and leak-scrub checks
# but no sentence or Missing/Next check. --all checks all text.
#
# With --upstream, skip changed records whose HEAD blobs match the upstream ref.
# Reject an upstream ref that does not resolve.
#
# Usage: records-lint.sh --orbit-root <dir> [--repo <owner/name>] [--base <ref>] [--upstream <ref>] [--all]
# Exit: 0 clean; 10 validate; 11 leak scrub; 12 sentence; 13 Missing/Next;
#       14 local path; 15 initiative; 16 interview; 17 scope; 18 evidence;
#       19 provenance; 20 usage or missing tool.
# Slice options: --slice <id>, --pr-body <file>, --pr <number>, --tickets <file>.

set -u

MAX_WORDS=25
orbit_root=""
repo="me2resh/apexyard"
base="origin/dev"
check_all=0
upstream=""
slice_id=""; pr_body=""; pr_number=""; tickets=""

usage() {
  echo "Usage: records-lint.sh --orbit-root <dir> [--repo <owner/name>] [--base <ref>] [--upstream <ref>] [--all]" >&2
  exit 20
}

while [ $# -gt 0 ]; do
  case "$1" in
    --orbit-root) [ $# -ge 2 ] || usage; orbit_root="$2"; shift 2 ;;
    --repo) [ $# -ge 2 ] || usage; repo="$2"; shift 2 ;;
    --upstream) [ $# -ge 2 ] || usage; upstream="$2"; shift 2 ;;
    --base) [ $# -ge 2 ] || usage; base="$2"; shift 2 ;;
    --tickets) [ $# -ge 2 ] || usage; tickets="$2"; [ -f "$tickets" ] || usage; shift 2 ;;
    --all) check_all=1; shift ;;
    --slice) [ $# -ge 2 ] || usage; slice_id="$2"; shift 2 ;;
    --pr-body) [ $# -ge 2 ] || usage; pr_body="$2"; shift 2 ;;
    --pr) [ $# -ge 2 ] || usage; pr_number="$2"; shift 2 ;;
    *) usage ;;
  esac
done
[ -d "$orbit_root" ] || { echo "records-lint: record directory not found: $orbit_root" >&2; exit 20; }
command -v jq >/dev/null 2>&1 || { echo "records-lint: jq is required." >&2; exit 20; }

ORBIT_BIN="${ORBIT_BIN:-orbit}"
command -v "$ORBIT_BIN" >/dev/null 2>&1 || {
  echo "records-lint: ORBIT CLI not found. Install orbit-spec or set ORBIT_BIN." >&2
  exit 20
}
script_dir="$(cd "$(dirname "$0")" && pwd)"
leak_scrub="$script_dir/../../../hooks/check-private-refs-runtime.sh"
[ -f "$leak_scrub" ] || { echo "records-lint: leak scrub not found at $leak_scrub" >&2; exit 20; }

fail() { # code check file message
  echo "records-lint: FAIL [$2] ${3:+$3: }$4" >&2
  exit "$1"
}

# Compare committed blobs at the same path. Keep files absent from either ref.
upstream_skipped=()
if [ -n "$upstream" ]; then
  upstream_top=$(git -C "$orbit_root" rev-parse --show-toplevel) ||
    fail 20 upstream "" "Cannot resolve the repository."
  upstream_top=$(cd "$upstream_top" && pwd -P)
  upstream=$(git -C "$upstream_top" rev-parse --verify --end-of-options "$upstream^{commit}" 2>/dev/null) ||
    fail 20 upstream "" "Cannot resolve the upstream ref."
  trap 'echo "records-lint: notice: skipped ${#upstream_skipped[@]} upstream record(s)." >&2' EXIT
fi

skip_upstream_record() {
  [ -n "$upstream" ] || return 1
  local path="$1" head_blob upstream_blob seen
  case "$path" in
    /*) path="$(cd "$(dirname "$path")" && pwd -P)/${path##*/}" ;;
  esac
  path="${path#"$upstream_top"/}"
  head_blob=$(git -C "$upstream_top" rev-parse --verify "HEAD:$path" 2>/dev/null) || return 1
  upstream_blob=$(git -C "$upstream_top" rev-parse --verify "$upstream:$path" 2>/dev/null) || return 1
  [ "$head_blob" = "$upstream_blob" ] || return 1
  for seen in ${upstream_skipped[@]+"${upstream_skipped[@]}"}; do
    [ "$seen" != "$path" ] || return 0
  done
  upstream_skipped+=("$path")
  return 0
}

# 1. Validate.
if ! out=$("$ORBIT_BIN" validate --all --root "$orbit_root" 2>&1); then
  fail 10 validate "" "orbit validate --all failed: $out"
fi

# Initiative scope is checked even with --all, including deleted records and history.
branch=$(git -C "$orbit_root" branch --show-current 2>/dev/null) || branch=""
case "$branch" in orbit/*)
  # shellcheck source=../../../hooks/_lib-orbit-records.sh
  . "$script_dir/../../../hooks/_lib-orbit-records.sh"
  orbit_records_branch_shape "$branch" && orbit_records_initiative "$orbit_root" "$branch" ||
    fail 15 initiative "" "No matching plan record exists for the branch initiative."
  plan_id="plan-$ORBIT_INITIATIVE"
  scope_top=$(git -C "$orbit_root" rev-parse --show-toplevel)
  scope_base=$(git -C "$orbit_root" merge-base "$base" HEAD) ||
    fail 15 initiative "" "Cannot resolve the initiative comparison base."
  scope_files=()
  while IFS= read -r -d '' f; do scope_files+=("$f"); done < <(
    { git -C "$scope_top" diff --name-only --no-renames -z "$scope_base" -- docs/orbit/
      git -C "$scope_top" ls-files --others --exclude-standard -z -- docs/orbit/; })
  kept_scope_files=()
  for f in ${scope_files[@]+"${scope_files[@]}"}; do
    skip_upstream_record "$f" || kept_scope_files+=("$f")
  done
  scope_files=(${kept_scope_files[@]+"${kept_scope_files[@]}"})
  snapshots=()
  for f in ${scope_files[@]+"${scope_files[@]}"}; do
    case "$f" in docs/orbit/reconciliations/*.json)
      if [ -f "$scope_top/$f" ]; then
        snap=$(jq -er --arg p "$plan_id" 'select(.planId == $p) | .projectSnapshotId' "$scope_top/$f") ||
          fail 15 initiative "$f" "Record belongs to another initiative."
        snapshots+=("$snap")
      fi ;;
    esac
  done
  for f in ${scope_files[@]+"${scope_files[@]}"}; do
    case "$f" in
      docs/orbit/plans/*.notes.md)
        [ "${f##*/}" = "$plan_id.notes.md" ] || fail 15 initiative "$f" "Notes belong to another initiative."
        continue ;;
      *.json) ;;
      *) fail 15 initiative "$f" "Cannot establish record initiative." ;;
    esac
    if [ -f "$scope_top/$f" ]; then record=$(cat "$scope_top/$f")
    else record=$(git -C "$scope_top" show "$scope_base:$f") || fail 15 initiative "$f" "Cannot read deleted record."; fi
    case "$f" in
      docs/orbit/plans/*) owner=$(printf '%s' "$record" | jq -er '.id') ;;
      # A history file is a superseded plan (owner in .id) or reconciliation (owner in .planId).
      docs/orbit/history/*) owner=$(printf '%s' "$record" | jq -er '.planId // .id') ;;
      docs/orbit/slices/*|docs/orbit/reconciliations/*) owner=$(printf '%s' "$record" | jq -er '.planId') ;;
      docs/orbit/snapshots/*)
        id=$(printf '%s' "$record" | jq -er '.id') || fail 15 initiative "$f" "Cannot read snapshot ID."
        found=0
        for snap in ${snapshots[@]+"${snapshots[@]}"}; do [ "$snap" != "$id" ] || found=1; done
        [ "$found" -eq 1 ] || fail 15 initiative "$f" "Snapshot is not referenced by a changed reconciliation."
        continue ;;
      *) fail 15 initiative "$f" "Cannot establish record initiative." ;;
    esac
    [ "$owner" = "$plan_id" ] || fail 15 initiative "$f" "Record belongs to another initiative."
  done
;; esac

# Slice checks use the base tip to prevent lost statuses.
case "$branch" in orbit/*) ;; *)
  if [ -n "$slice_id" ] || [ -n "$pr_body" ]; then
  # shellcheck source=./slice-pr-lint.sh
  . "$script_dir/slice-pr-lint.sh"
  slice_pr_lint
  fi
;; esac

# Select the files for checks 2 to 6.
files=()
use_diff=0
if [ "$check_all" -eq 0 ]; then
  if git -C "$orbit_root" rev-parse --verify -q "$base" >/dev/null 2>&1; then
    use_diff=1
  else
    echo "records-lint: notice: base ref $base not found, so the lint checks every record file." >&2
  fi
fi
if [ "$use_diff" -eq 1 ]; then
  top=$(git -C "$orbit_root" rev-parse --show-toplevel)
  # Diff against the merge base, not the tip of the base ref.
  mb=$(git -C "$orbit_root" merge-base "$base" HEAD 2>/dev/null) || mb="$base"
  while IFS= read -r f; do
    [ -n "$f" ] && [ -f "$top/$f" ] && files+=("$top/$f")
  done < <({ git -C "$orbit_root" diff --name-only "$mb" -- .
             git -C "$orbit_root" ls-files --others --exclude-standard --full-name -- .; } | sort -u)
else
  while IFS= read -r f; do files+=("$f"); done < <(find "$orbit_root" -type f \( -name '*.json' -o -name '*.md' \) | sort)
fi
# Keep records and notes, drop everything else.
sel=()
for f in ${files[@]+"${files[@]}"}; do
  skip_upstream_record "$f" && continue
  case "$f" in */history/*) continue ;; esac  # frozen Plan revisions
  case "$f" in *.json|*.md) sel+=("$f") ;; esac
done
if [ "${#sel[@]}" -eq 0 ]; then
  echo "records-lint: OK (validate passed; no changed record files)"
  exit 0
fi

# Filter for both field readers: a text path, not an identifier or date.
SKIP_RE='^(id|specVersion|status|basedOn|repositories|repositoryId|commit|branch|url|observedAt|reconciledAt|outcomeId|criterionId|planId|planRevision|projectSnapshotId|contributesTo)$|Id$'

# Text fields of a record: every string except identifiers, provenance and dates.
text_fields() {
  jq -r --arg skip "$SKIP_RE" '
    . as $r
    | [paths(type == "string")]
    | .[]
    | select(all(.[]; tostring | test($skip) | not))
    | . as $p | $r | getpath($p)
  ' "$1" 2>/dev/null
}

# old_copy <file>: write the merge-base copy of a tracked file to a temp file
# and print its path. Print nothing when the lint checks all text or the file
# is new.
old_copy() {
  [ "$use_diff" -eq 1 ] || return 0
  local rel tmp
  rel="${1#"$top"/}"
  tmp=$(mktemp "${TMPDIR:-/tmp}/records-lint-old.XXXXXX") || return 0
  if git -C "$top" show "$mb:$rel" > "$tmp" 2>/dev/null && jq -e . "$tmp" >/dev/null 2>&1; then
    echo "$tmp"
  else
    rm -f "$tmp"
  fi
}

# changed_text <file>: the text that checks 3 needs. Text fields whose value
# differs from the merge base (JSON), or added and changed lines (notes).
changed_text() {
  local f="$1" old
  case "$f" in
    *.json)
      old=$(old_copy "$f")
      if [ -z "$old" ]; then text_fields "$f"; return 0; fi
      jq -r --slurpfile old "$old" --arg skip "$SKIP_RE" '
        . as $r | $old[0] as $o
        | [paths(type == "string")] | .[]
        | select(all(.[]; tostring | test($skip) | not))
        | . as $p
        | select((try ($o | getpath($p)) catch null) != ($r | getpath($p)))
        | $r | getpath($p)
      ' "$f" 2>/dev/null
      rm -f "$old"
      ;;
    *)
      if [ "$use_diff" -eq 1 ] && git -C "$top" ls-files --error-unmatch "${f#"$top"/}" >/dev/null 2>&1 \
         && git -C "$top" cat-file -e "$mb:${f#"$top"/}" 2>/dev/null; then
        git -C "$top" diff -U0 "$mb" -- "${f#"$top"/}" | grep '^+' | grep -v '^+++' | sed 's/^+//'
      else
        cat "$f"
      fi
      ;;
  esac
}

# 2. Leak scrub, one pass per file over its text.
for f in "${sel[@]}"; do
  tmp=$(mktemp "${TMPDIR:-/tmp}/records-lint.XXXXXX") || fail 20 leak-scrub "$f" "cannot create a temp file"
  case "$f" in
    *.json) text_fields "$f" > "$tmp" ;;
    *) cp "$f" "$tmp" ;;
  esac
  if ! out=$("$leak_scrub" "$repo" "records" "$tmp" 2>&1); then
    rm -f "$tmp"
    fail 11 leak-scrub "$f" "the leak scrub blocked this text. $out"
  fi
  rm -f "$tmp"
done

# 3. Sentence length, record JSON only. Notes are prose, a person reads them.
for f in "${sel[@]}"; do
  case "$f" in *.json) ;; *) continue ;; esac
  long=$(changed_text "$f" | awk -v max="$MAX_WORDS" '
    { gsub(/[.!?]+[ \t]+/, "&\n"); n = split($0, parts, "\n")
      for (i = 1; i <= n; i++) { w = split(parts[i], words, /[ \t]+/); c = 0
        for (j = 1; j <= w; j++) if (words[j] != "") c++
        if (c > max) { print c ": " substr(parts[i], 1, 60) "..."; exit } } }')
  [ -z "$long" ] || fail 12 sentence "$f" "a sentence has more than $MAX_WORDS words ($long)"
done

# 4. Missing and Next rule, reconciliation records only.
for f in "${sel[@]}"; do
  case "$f" in *.json) ;; *) continue ;; esac
  [ "$(jq -r '.criterionAssessments | type' "$f" 2>/dev/null)" = "array" ] || continue
  old=$(old_copy "$f")
  if [ -n "$old" ]; then
    # Only an assessment whose explanation or status changed.
    bad=$(jq -r --slurpfile old "$old" '
      (($old[0].criterionAssessments // []) | if type == "array" then . else [] end) as $oa
      | .criterionAssessments[] | . as $a
      | select(($oa | map(select(.criterionId == $a.criterionId)) | .[0]) as $p
          | ($p.explanation // null) != ($a.explanation // null) or ($p.status // null) != ($a.status // null))
      | select(.status != "achieved")
      | select((.explanation // "") | test("^Missing: .+ Next: .+") | not)
      | .criterionId' "$f" | head -1)
    rm -f "$old"
  else
    bad=$(jq -r '.criterionAssessments[]
    | select(.status != "achieved")
    | select((.explanation // "") | test("^Missing: .+ Next: .+") | not)
    | .criterionId' "$f" | head -1)
  fi
  [ -z "$bad" ] || fail 13 missing-next "$f" "criterion $bad is not achieved. Its explanation must read \"Missing: <what>. Next: <action>.\""
done

# 5. Local paths, records and notes.
pattern='(/Users/|/home/[A-Za-z]|/private/tmp|/var/folders/|/tmp/|[A-Za-z]:\\\\|~/)'
for f in "${sel[@]}"; do
  hit=$(grep -nE "$pattern" "$f" | head -1)
  [ -z "$hit" ] || fail 14 local-path "$f" "a local path appears at line ${hit%%:*}. Use a repository-relative path."
done

# 6. Interview evidence for each new or changed Plan (all Plans with --all).
for f in "${sel[@]}"; do
  case "$f" in */plans/*.json) ;; *) continue ;; esac
  plan_id=$(jq -er '.id' "$f") || fail 16 interview "$f" "Cannot read Plan ID."
  notes="$(dirname "$f")/$plan_id.notes.md"
  [ -f "$notes" ] && grep -qE '^## Interview[[:space:]]*$' "$notes" ||
    fail 16 interview "$notes" "Missing ## Interview section."
  for question in q1-outcome q2-intent q3-outcomes q4-acceptance q5-constraints q6-save; do
    awk -v question="$question" '
      /^## Interview[[:space:]]*$/ { interview=1; next }
      /^#{1,2}[[:space:]]/ { interview=0 }
      interview && $0 ~ "^- [0-9]{4}-[0-9]{2}-[0-9]{2}, " question ":[[:space:]]*[^[:space:]]" { found=1 }
      END { exit !found }
    ' "$notes" || fail 16 interview "$notes" "Missing dated answer for $question in ## Interview."
  done
done

echo "records-lint: OK (${#sel[@]} file(s) checked)"
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall