ecoportal-api 0.10.16 → 0.10.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6998cdda6bc8a40de4a368ab81d522cd9828cd8dbbb559a59948976e3f57dcb
-  data.tar.gz: ba86db2250fad20b429d1f5afa26a08b064e0eeb14ea90f096dceaf4973d362e
+  metadata.gz: e6d3ab5bbf5ab30cdf4a53a91eb9727156759a19efc68754d475ecc0a8fa45ba
+  data.tar.gz: 9fcd22e6b949e5b3ea302fabeedb5b502035d322b27b8e91c8b5e4ee3980869d
 SHA512:
-  metadata.gz: fb91f3d928853691c913efbd17f0db1bda9343c44b1449275864fc16e053ef0d3cd1f14fd64e90625fc3ea991a81494c2a7315d318666184c14dd3acd51344f4
-  data.tar.gz: 57f8fc55f1d55f1733fe98720477739d72b063bae1f4a16665132e20a5560192275b5815e25d99097400fd2f5de4c7914a35823a8e5168ea34187e4e5d9ae98c
+  metadata.gz: 4a39f97efb44f84488674df6c29d0efc5f16a2f7083efedb2d2be866dff771629f29649ca4fd66809f5b53c4c700d8fd4f4350a0eca43d260a22e2babd71dd5c
+  data.tar.gz: e1931ea7266e1b32b198f1fbf0ef218b156b2b8ab2a54ccf7b9de3d95418e6154e680865fc539248147bd1a3960188166e232ced83514f400aaa309a8bca8bad

data/.ai-assistance/.gitignore

@@ -0,0 +1,2 @@
+# Machine-local, never committed (see conventions/local-paths-protocol.md)
+local/

data/.ai-assistance/bridge/.gitignore

@@ -0,0 +1,10 @@
+# Bridge runtime state and message files are machine-local -- never committed.
+# Only the structural scaffold (bridge/CLAUDE.md, .gitkeep placeholders, this file) is
+# tracked; processed pairs under archive/ stay trackable for an optional audit trail.
+inbox/*
+outbox/*
+LOCK
+STATUS
+queue/
+!inbox/.gitkeep
+!outbox/.gitkeep

data/.ai-assistance/bridge/CLAUDE.md

@@ -0,0 +1,96 @@
+# Bridge Protocol -- CoWork <-> Claude Code Delegation
+
+The bridge is a file-based task delegation system for handing work between the CoWork
+environment and the Claude Code (CLI) environment. Use it when one environment has
+connector access (e.g. GitLab MCP, Gemini) that the other doesn't.
+
+**The bridge is for delegation of discrete tasks only -- not for working tree changes.**
+All file edits happen within a single environment. The bridge passes task context and results.
+
+---
+
+## Folder structure
+
+```
+.ai-assistance/bridge/
+  inbox/         ← Tasks waiting to be processed (CoWork writes; Code reads)
+  outbox/        ← Completed results (Code writes; CoWork reads)
+  archive/       ← Completed inbox/outbox pairs (audit trail)
+  CLAUDE.md      ← This file — bridge protocol documentation
+  LOCK           ← Concurrency control (acquired/expires/intent/connector)
+  STATUS         ← Aggregated status (pending/in-progress counts)
+```
+
+---
+
+## Task lifecycle
+
+```
+PENDING → IN_PROGRESS → DONE (or FAILED)
+CoWork writes inbox/  →  Code reads + processes  →  Code writes outbox/  →  CoWork reads + archives
+```
+
+---
+
+## Task filename convention
+
+```
+<username>-<uuid7>-<slug>.md
+```
+
+Examples:
+- `oscar-01j2k3l4m5n6-gemini-review.md`
+- `oscar-01j2k3l4m5n6-gitlab-mr-check.md`
+
+---
+
+## Task file format
+
+```markdown
+---
+task_id: <uuid7>
+status: PENDING           # PENDING | IN_PROGRESS | DONE | FAILED
+connector: gemini         # which connector is needed: gemini | gitlab | rovo | local-git
+created_by: oscar
+created_at: 2026-06-08T01:00:00Z
+expires_at: 2026-06-08T02:00:00Z
+intent: >
+  One sentence describing what needs to happen.
+---
+
+## Context
+
+[Everything the processing agent needs to understand and execute the task.]
+
+## Expected output
+
+[What should be written to outbox/ — format, length, key fields.]
+```
+
+---
+
+## LOCK file
+
+Prevents concurrent bridge writes. Acquired before writing to inbox; released when done.
+
+```
+AGENT: claude-code
+USER: oscar
+ACQUIRED: 2026-06-08T01:00:00Z
+EXPIRES: 2026-06-08T01:30:00Z
+INTENT: running gemini-review task oscar-01j2k3l4m5n6
+CONNECTOR: gemini
+```
+
+If LOCK is present and not expired: wait or fail. If LOCK is expired: it can be overwritten.
+
+---
+
+## Autonomy zones (from conventions/permission-guidance.md)
+
+| Zone | Operations | Approval needed |
+|---|---|---|
+| 1 | All reads, git status/log/diff, tests, linting | None |
+| 2 | Edit + commit any file in repo (non-main branch) | Notify in same turn |
+| 3 | First commit to a sibling repo | State intent, wait one exchange |
+| 4 | git push, main branch changes, API/gemspec changes | Always confirm |

data/.ai-assistance/capabilities/assumptions-log.md

@@ -0,0 +1,23 @@
+# Assumptions Log
+
+Dated log of assumptions made during development. Items are verified, marked STALE when
+superseded, or flagged NEEDS_REVIEW when they depend on external state that may change.
+
+---
+
+## Format
+
+```
+[YYYY-MM-DD] [STATUS] Assumption text
+  Source: where this came from
+  Verified-by: how it was confirmed (or "not yet verified")
+  Notes: anything relevant
+```
+
+Status values: `VERIFIED` | `NEEDS_REVIEW` | `STALE` | `REFUTED`
+
+---
+
+## Assumptions
+
+<!-- Add entries below -- most recent first -->

data/.ai-assistance/scripts/bridge-inbox-check.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# bridge-inbox-check.sh -- session-start actuator for the bridge inbox.
+#
+# Closes an actuation-coverage gap: unread cross-project bridge messages used to be
+# visible only if someone manually ran a command. This is the trigger/clock that
+# surfaces them automatically at session start, mirroring the standards-inbox report
+# line (see CLAUDE.md and standards/governance/standards-request-protocol.md).
+#
+# DETERMINISTIC and zero-LLM: it just scans .ai-assistance/bridge/inbox/ for unread
+# messages (STATUS: PENDING) and prints one summary line plus one line per message:
+#
+#   [bridge] N unread message(s)
+#   - {title} from {FROM}
+#
+# Contract (mirrors the other hook scripts):
+#   - Silent (no output) and exit 0 when the inbox is empty or has no unread messages.
+#   - NEVER fails fatally -- always exits 0, even on a malformed file or missing dir.
+#   - No side effects: read-only, does not touch or move any message.
+#
+# --verbose (added 2026-07-23, dashboard-cockpit-v5): when the bridge dir HAS been
+# adopted (inbox/ exists) but there is nothing to report, prints one friendly
+# "[bridge] inbox clear" line instead of nothing -- a manual click with no output
+# otherwise reads as "did this even run?". Bridge-not-adopted (no inbox dir at all)
+# stays silent even with --verbose. DEFAULT (no flag) behavior is UNCHANGED: the
+# SessionStart hook below still calls this with no arguments.
+#
+# Wired as a SessionStart hook in .claude/settings.json:
+#   bash scripts/bridge-inbox-check.sh 2>/dev/null || true
+#
+# Manual run (same output): bash scripts/bridge-inbox-check.sh
+# Manual run, friendly-on-empty: bash scripts/bridge-inbox-check.sh --verbose
+set -u
+
+VERBOSE=0
+[ "${1:-}" = "--verbose" ] && VERBOSE=1
+reported=0
+
+# Resolve the inbox by walking up from this script's OWN location, so it works whether
+# the script is deployed at <root>/scripts/ (ep-ai-standards itself) or at
+# <root>/.ai-assistance/scripts/ (the standard fleet deploy target) -- and from any cwd.
+# A fixed "$(dirname "$0")/.." only works for the first layout; in the deploy target it
+# resolves to <root>/.ai-assistance/.ai-assistance/bridge/inbox and silently finds nothing.
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)" || exit 0
+INBOX=""
+d="$SCRIPT_DIR"
+for _ in 1 2 3 4 5; do
+  if [ -d "$d/.ai-assistance/bridge/inbox" ]; then INBOX="$d/.ai-assistance/bridge/inbox"; break; fi
+  d="$(dirname "$d")"
+done
+
+# No inbox -> nothing to report.
+[ -n "$INBOX" ] && [ -d "$INBOX" ] || exit 0
+
+# An "unread" message is a *.md file whose header carries STATUS: PENDING.
+# (PENDING = not yet picked up by the receiving agent; IN_PROGRESS/DONE/FAILED are read.)
+unread=""
+count=0
+
+for f in "$INBOX"/*.md; do
+  # Guard against the literal glob when the folder is empty.
+  [ -e "$f" ] || continue
+
+  # Only inspect the header block (first ~15 lines) -- cheap and format-stable.
+  header="$(head -n 15 "$f" 2>/dev/null || true)"
+
+  # Unread == STATUS: PENDING (case-insensitive, tolerant of surrounding whitespace).
+  printf '%s\n' "$header" | grep -Eiq '^[[:space:]]*STATUS:[[:space:]]*PENDING[[:space:]]*$' || continue
+
+  # Title: the text after "# TASK:" on line 1; fall back to the filename.
+  title="$(printf '%s\n' "$header" \
+    | grep -Ei '^#[[:space:]]*TASK:' \
+    | head -n 1 \
+    | sed -E 's/^#[[:space:]]*TASK:[[:space:]]*//I' 2>/dev/null || true)"
+  [ -n "$title" ] || title="$(basename "$f" .md)"
+
+  # Sender: the text after "FROM:"; fall back to "unknown".
+  from="$(printf '%s\n' "$header" \
+    | grep -Ei '^[[:space:]]*FROM:' \
+    | head -n 1 \
+    | sed -E 's/^[[:space:]]*FROM:[[:space:]]*//I' 2>/dev/null || true)"
+  [ -n "$from" ] || from="unknown"
+
+  count=$((count + 1))
+  unread="${unread}- ${title} from ${from}
+"
+done
+
+# Report unread inbox messages (if any).
+if [ "$count" -gt 0 ]; then
+  printf '[bridge] %d unread message(s)\n' "$count"
+  printf '%s' "$unread"
+  reported=1
+fi
+
+# Stranded-message guard: a STATUS: PENDING file in archive/ is a lifecycle contradiction --
+# a message consumed-and-archived without being flipped to DONE (or archived before it was
+# processed). It is invisible to the inbox scan above, so it silently looks handled. Surface it.
+ARCHIVE="$(dirname "$INBOX")/archive"
+stranded=0
+if [ -d "$ARCHIVE" ]; then
+  for f in "$ARCHIVE"/*.md; do
+    [ -e "$f" ] || continue
+    head -n 15 "$f" 2>/dev/null | grep -Eiq '^[[:space:]]*STATUS:[[:space:]]*PENDING[[:space:]]*$' || continue
+    if [ "$stranded" -eq 0 ]; then
+      printf '[bridge] WARNING: STATUS: PENDING file(s) in archive/ (stranded -- consumed without closing the loop, or archived before processing):\n'
+    fi
+    stranded=$((stranded + 1))
+    printf '  - %s\n' "$(basename "$f")"
+    reported=1
+  done
+fi
+
+# --verbose, nothing to report: one friendly line so a manual click doesn't read as
+# "did this even run?".
+if [ "$VERBOSE" -eq 1 ] && [ "$reported" -eq 0 ]; then
+  printf '[bridge] inbox clear -- no unread messages, no stranded archive entries.\n'
+fi
+
+exit 0

data/.ai-assistance/scripts/bridge-init.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# bridge-init.sh
+# Detects environment, scans bridge/inbox for pending tasks belonging to current user.
+# Output: single JSON line for the agent to consume.
+# Usage: source .ai-assistance/scripts/bridge-init.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BRIDGE_DIR="$SCRIPT_DIR/../bridge"
+INBOX_DIR="$BRIDGE_DIR/inbox"
+
+# --- Environment detection ---
+# Prefer explicit env var; fall back to "code" (this script is most useful in Code)
+ENV="${CLAUDE_ENV:-code}"
+
+# --- Username detection ---
+# Prefer explicit env var; fall back to git config
+if [ -n "${BRIDGE_USER:-}" ]; then
+  USER_SLUG="$BRIDGE_USER"
+else
+  GIT_USER=$(git config user.name 2>/dev/null || echo "unknown")
+  USER_SLUG=$(echo "$GIT_USER" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
+fi
+
+# --- Stale threshold (seconds) ---
+# IN_PROGRESS tasks older than this are flagged as stale (likely a crashed session).
+STALE_THRESHOLD_SECONDS=3600  # 1 hour
+
+# --- Scan inbox ---
+pending_tasks=()
+stale_tasks=()
+
+if [ -d "$INBOX_DIR" ]; then
+  while IFS= read -r -d '' file; do
+    filename=$(basename "$file")
+    # Only files prefixed with this user's slug
+    if [[ "$filename" == ${USER_SLUG}-* ]]; then
+      if grep -q "^STATUS: PENDING" "$file" 2>/dev/null; then
+        pending_tasks+=("$filename")
+      elif grep -q "^STATUS: IN_PROGRESS" "$file" 2>/dev/null; then
+        # Check how old the file is
+        if command -v stat &>/dev/null; then
+          # GNU stat (Linux/Git-Bash): -c %Y gives mtime as epoch seconds
+          # macOS stat uses -f %m — try GNU first, fall back gracefully
+          mtime=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo 0)
+          now=$(date +%s)
+          age=$(( now - mtime ))
+          if [ "$age" -ge "$STALE_THRESHOLD_SECONDS" ]; then
+            stale_tasks+=("$filename")
+          fi
+        fi
+        # If stat is unavailable we silently skip stale detection for this file
+      fi
+    fi
+  done < <(find "$INBOX_DIR" -maxdepth 1 -name "*.md" \
+    -not -name "*.draft.md" \
+    -not -name "*.local.md" \
+    -not -name ".gitkeep" \
+    -print0 2>/dev/null)
+fi
+
+# --- Build JSON output ---
+count=${#pending_tasks[@]}
+stale_count=${#stale_tasks[@]}
+
+tasks_json="["
+for i in "${!pending_tasks[@]}"; do
+  tasks_json+="\"${pending_tasks[$i]}\""
+  [ $i -lt $((count - 1)) ] && tasks_json+=","
+done
+tasks_json+="]"
+
+stale_json="["
+for i in "${!stale_tasks[@]}"; do
+  stale_json+="\"${stale_tasks[$i]}\""
+  [ $i -lt $((stale_count - 1)) ] && stale_json+=","
+done
+stale_json+="]"
+
+output="{\"env\":\"$ENV\",\"user\":\"$USER_SLUG\",\"pending\":$count,\"tasks\":$tasks_json,\"stale\":$stale_count,\"stale_tasks\":$stale_json}"
+
+# Write to status file so Code can read it on startup (hook stdout is not injected into context)
+echo "$output" > "$BRIDGE_DIR/STATUS"
+
+echo "$output"

data/.ai-assistance/scripts/confine-to-subtree.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# confine-to-subtree.sh -- PreToolUse hook (matcher: Bash) for a SUBFOLDER-SCOPED
+# deployment. Denies Bash commands that WRITE or DELETE outside the project subtree
+# (the cwd Claude was launched from, e.g. <core-repo>/doc/scripts), so the AI cannot
+# modify the rest of the host repo. READS anywhere are allowed (the scripts framework
+# needs to read the app's models); git is allowed (it manages the repo, incl the
+# parent .git). Standard: standards/tooling/subfolder-deployment.md.
+#
+# Structured deny + exit 0 (holds under --dangerously-skip-permissions). Reads JSON via
+# python -c (a heredoc would steal stdin). Fails OPEN on any parse error. Heuristic
+# (command-string) confinement -- pair with settings.deny Edit/Write(../**), which
+# reliably confines Claude's own file tools, for defense-in-depth.
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+exec "$PY" -c "
+import sys, json, re
+try:
+    data = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(0)
+if data.get(\"tool_name\") != \"Bash\":
+    sys.exit(0)
+cmd = (data.get(\"tool_input\") or {}).get(\"command\", \"\") or \"\"
+cwd = (data.get(\"cwd\") or \"\").replace(chr(92), \"/\").rstrip(\"/\")
+
+def deny(reason):
+    print(json.dumps({\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\",
+        \"permissionDecision\": \"deny\", \"permissionDecisionReason\": reason}}))
+    sys.exit(0)
+
+# git manages the whole repo (incl the parent .git); allow it. Commit-scope discipline
+# (git add <subtree>) is a documented convention, not enforced here.
+if re.match(r\"^\s*git\b\", cmd):
+    sys.exit(0)
+
+WRITE = r\"(?:\brm\b|\brmdir\b|\bmv\b|\bcp\b|\bdd\b|\btee\b|\btruncate\b|\binstall\b|\bmkdir\b|\bln\b|>>?)\"
+if not re.search(WRITE, cmd):
+    sys.exit(0)  # read-only command -> always allowed
+
+# Signal 1: a parent-escaping relative path (../) in a write command.
+if re.search(r\"\.\./\", cmd):
+    deny(\"Blocked: write/delete escapes the project subtree via ../ (subfolder-scoped deploy).\")
+
+# Signal 2: an absolute path token not under cwd (and not a temp dir).
+ALLOWED = (\"/tmp/\", \"/var/tmp/\", \"/private/tmp/\", \"/var/folders/\", \"/private/var/folders/\")
+for raw in cmd.split():
+    t = raw.strip(chr(34)).strip(chr(39)).replace(chr(92), \"/\")
+    if not (t.startswith(\"/\") or re.match(r\"^[A-Za-z]:/\", t)):
+        continue
+    if any(t.startswith(a) for a in ALLOWED):
+        continue
+    if cwd and (t == cwd or t.startswith(cwd + \"/\")):
+        continue  # inside the subtree
+    deny(\"Blocked: write/delete targets an absolute path outside the project subtree \"
+         \"(subfolder-scoped deploy): \" + raw)
+
+sys.exit(0)  # writes appear to stay within the subtree -> allow
+"

data/.ai-assistance/scripts/dirty-tree-guard.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# dirty-tree-guard.sh -- session hook that warns about a dirty tree ON THE DEFAULT BRANCH.
+#
+# Closes a recurring hygiene gap (Oscar-flagged, memory feedback-keep-main-tree-clean):
+# loose, uncommitted files left behind on main/master -- often in a sibling repo after
+# agent work. The rule is: work happens on a feature branch; the default branch stays
+# clean. This surfaces a violation the moment it exists, at session start and stop.
+#
+# DETERMINISTIC and zero-LLM. It warns ONLY when BOTH are true:
+#   (a) HEAD is the repo DEFAULT branch (main or master -- DETECTED, not hardcoded), AND
+#   (b) git status --porcelain is non-empty (the tree has uncommitted changes).
+# On a feature branch a dirty tree is normal mid-work -> stay SILENT.
+#
+#   [dirty-tree-guard] N uncommitted change(s) on <branch> (default branch):
+#     - path/one
+#     ... (+M more)
+#   hint: move work to a feature branch (bash .ai-assistance/scripts/new-feature-branch.sh feat/<slug>) before committing.
+#
+# Contract (mirrors the other hook scripts):
+#   - Silent (no output) and exit 0 when clean, or when NOT on the default branch.
+#   - Safe outside a git repo: detects and exits 0 silently.
+#   - NEVER fails fatally -- always exits 0 (advisory only). Read-only, no side effects.
+#
+# Wired as a SessionStart AND Stop hook in .claude/settings.json:
+#   bash .ai-assistance/scripts/dirty-tree-guard.sh 2>/dev/null || true
+#
+# Manual run (same output): bash scripts/dirty-tree-guard.sh
+set -u
+
+# Cap on how many loose paths to list before summarising the remainder.
+MAX_PATHS=15
+
+# git present? If not, this is not a context we can (or should) inspect.
+command -v git >/dev/null 2>&1 || exit 0
+
+# Inside a git work tree? Run from wherever the session cwd is; git resolves the repo.
+# Outside any repo this prints "false" (or errors) -> exit 0 silently.
+in_tree="$(git rev-parse --is-inside-work-tree 2>/dev/null || true)"
+[ "$in_tree" = "true" ] || exit 0
+
+# Current branch. Detached HEAD -> empty -> treat as "not the default branch" -> silent.
+branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+[ -n "$branch" ] && [ "$branch" != "HEAD" ] || exit 0
+
+# Detect the DEFAULT branch -- never hardcode. Preference order:
+#   1. origin/HEAD symbolic ref (the remote default, e.g. origin/main)
+#   2. a local main, then master, if either exists
+# Fall back to empty (no detectable default) -> silent, so we never warn on a repo
+# whose default we could not establish.
+default=""
+remote_head="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+if [ -n "$remote_head" ]; then
+  # Strip the leading origin/ prefix to get the bare branch name.
+  default="${remote_head#origin/}"
+fi
+if [ -z "$default" ]; then
+  if git show-ref --verify --quiet refs/heads/main 2>/dev/null; then
+    default="main"
+  elif git show-ref --verify --quiet refs/heads/master 2>/dev/null; then
+    default="master"
+  fi
+fi
+
+# Not on the default branch -> a dirty tree is expected mid-work -> silent.
+[ -n "$default" ] && [ "$branch" = "$default" ] || exit 0
+
+# On the default branch: is the tree dirty?
+status="$(git status --porcelain 2>/dev/null || true)"
+[ -n "$status" ] || exit 0
+
+# Dirty on default. Count and list (capped).
+total="$(printf '%s\n' "$status" | grep -c . || true)"
+[ -n "$total" ] || total=0
+[ "$total" -gt 0 ] || exit 0
+
+printf '[dirty-tree-guard] %s uncommitted change(s) on %s (default branch):\n' "$total" "$branch"
+
+shown=0
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  # Porcelain v1 line: 2-char status, a space, then the path. Strip the status prefix.
+  path="$(printf '%s' "$line" | cut -c4-)"
+  printf '  - %s\n' "$path"
+  shown=$((shown + 1))
+  [ "$shown" -ge "$MAX_PATHS" ] && break
+done <<INNER_EOF
+$status
+INNER_EOF
+
+if [ "$total" -gt "$shown" ]; then
+  printf '  ... (+%s more)\n' "$((total - shown))"
+fi
+
+printf 'hint: move work to a feature branch (bash .ai-assistance/scripts/new-feature-branch.sh feat/<slug>) before committing, then keep %s clean.\n' "$branch"
+
+exit 0