# https://github.com/astrojones/astrojones Project Manual
Generated at: 2026-07-18 18:08:27 UTC
## Table of Contents
- [Plugin Overview & System Architecture](#page-1)
- [Core Harness Tools, Serena Proxy & Workflow Skills](#page-2)
- [Memory & Perception Layer (cognee ↔ claude-mem)](#page-3)
- [Deployment, Drift Detection & Operations](#page-4)
## Plugin Overview & System Architecture
### Related Pages
Related topics: [Core Harness Tools, Serena Proxy & Workflow Skills](#page-2), [Deployment, Drift Detection & Operations](#page-4)
Related Source Files
The following source files were used to generate this page:
- [.claude-plugin/marketplace.json](https://github.com/astrojones/astrojones/blob/main/.claude-plugin/marketplace.json)
- [.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/.claude-plugin/plugin.json)
- [.claude/settings.json](https://github.com/astrojones/astrojones/blob/main/.claude/settings.json)
- [.mcp.json](https://github.com/astrojones/astrojones/blob/main/.mcp.json)
- [run-mcp.sh](https://github.com/astrojones/astrojones/blob/main/run-mcp.sh)
- [commands/harness-init.md](https://github.com/astrojones/astrojones/blob/main/commands/harness-init.md)
# Plugin Overview & System Architecture
## Purpose and Scope
The `astrojones` plugin is a Claude Code plugin that orchestrates repository-aware agent workflows. It packages several cooperating sub-plugins — notably `harness`, `deploy`, `perception`, and `mem` — under a single marketplace distribution so that an agent can bootstrap a project, monitor its state, deploy it, and recall prior context across sessions.
Distribution is handled through Claude Code's marketplace mechanism. `.claude-plugin/marketplace.json` describes the marketplace entry, and `.claude-plugin/plugin.json` provides the plugin manifest (name, version, description, sub-plugin list). At the time of writing, the manifest tracks v3.23.0 as the latest release, with `feat(mem): cognee ↔ claude-mem coexistence (P2)` shipped via PR #42 as the most recent change. Source: [.claude-plugin/plugin.json]()
## High-Level Architecture
The system is composed of three runtime layers wired together by configuration files at the repository root:
1. **Plugin layer** — marketplace and plugin manifests describe which sub-plugins ship together and at which version.
2. **Agent integration layer** — `.claude/settings.json` configures Claude Code's hooks, permissions, and tool wiring that the plugin relies on at runtime.
3. **MCP server layer** — `.mcp.json` declares Model Context Protocol servers that the agent calls as tools; `run-mcp.sh` is the launcher invoked for stdio servers.
Because the harness is stdio-based, delivery currently relies on Claude Code hooks rather than the experimental MCP server-push `claude/channel` capability, which is known to be unreliable from stdio servers (anthropic/claude-code #45563, #36431). This is the constraint behind issue #36. Source: [.mcp.json](), [run-mcp.sh]()
A simplified view of the runtime topology:
```mermaid
flowchart LR
User --> ClaudeCode[Claude Code]
ClaudeCode -->|hooks| Settings[".claude/settings.json"]
ClaudeCode -->|tools| MCP[".mcp.json servers"]
MCP --> Launcher[run-mcp.sh]
Launcher --> Plugins[harness / deploy / perception / mem]
Plugins --> RepoState["repo_state snapshot"]
```
## Sub-Plugins and Responsibilities
The plugin manifest groups several cooperating sub-plugins. Each owns a distinct concern:
- **harness** — bootstraps a repository for agent use. The `commands/harness-init.md` slash command drives `repo_bootstrap`, which is already parametrized. The harness ships at v3.9.2 with no version drift against its own manifest. Source: [commands/harness-init.md]()
- **deploy** — provides deploy-validation tooling. Its surface has drifted relative to the harness's deploy-validation checks, which is the motivation behind issue #37 ("T6 — De-hardcode the harness deploy tool"), currently P2 and release-blocked. Source: [.claude-plugin/plugin.json]()
- **perception** — runs a background daemon that maintains a `repo_state` snapshot and feeds a digest into the `UserPromptSubmit` hook. v1 covers branch/HEAD switches and merge conflicts. Planned extensions include external-edit detection for files the agent is editing (#34), CI-status folding (#33), and eventual consolidation of `repo_verify_changed` and `repo_health` into `repo_state` (#35). Source: [.claude/settings.json]()
- **mem** — memory subsystem. As of v3.23.0, it supports coexistence between `cognee` and `claude-mem`: the agent mirrors memories between the two, removes client-side capture, and gates recall off by default. Source: [.claude-plugin/plugin.json]()
## Configuration Surfaces
The repository root holds the configuration files that define how the plugin attaches to Claude Code and which tools it exposes. `.claude-plugin/marketplace.json` registers the plugin for marketplace distribution, `.claude-plugin/plugin.json` carries the version and sub-plugin metadata, `.claude/settings.json` configures hooks and permissions, `.mcp.json` declares MCP servers consumed by the agent, and `run-mcp.sh` is the launcher used for stdio servers. When the harness's deploy-validation surface is updated to consume the deploy plugin's contract directly, the changes flow through `.mcp.json` and `.claude/settings.json` rather than being hardcoded inside the harness — the explicit goal of issue #37. Source: [.mcp.json](), [.claude/settings.json](), [run-mcp.sh]()
## Active Development Threads
Several open issues shape the near-term architecture:
- **#37** targets de-hardcoding the harness's deploy tool so its validation surface stays in sync with the deploy plugin.
- **#36** tracks a future switch from hook-based delivery to `claude/channel` MCP push once stdio reliability improves upstream.
- **#35** proposes folding `repo_verify_changed` and `repo_health` into `repo_state` once perception is proven in practice.
- **#34** adds detection for external edits to files the agent is working on, using a `perception_touched.json` set hashed against watcher events.
- **#33** adds CI status to the perception snapshot by reusing `health._ci_check` on a timed interval.
These threads share a common direction: push more state into the perception snapshot and reduce on-demand verb tools, so the agent reaches for fewer manual commands and `repo_state` becomes the single primary surface for repository awareness.
---
## Core Harness Tools, Serena Proxy & Workflow Skills
### Related Pages
Related topics: [Plugin Overview & System Architecture](#page-1), [Deployment, Drift Detection & Operations](#page-4)
Related Source Files
The following source files were used to generate this page:
- [servers/harness-mcp/repo_agent_harness/server.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/server.py)
- [servers/harness-mcp/repo_agent_harness/context.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/context.py)
- [servers/harness-mcp/repo_agent_harness/impact.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/impact.py)
- [servers/harness-mcp/repo_agent_harness/git.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/git.py)
- [servers/harness-mcp/repo_agent_harness/symbols.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/symbols.py)
- [servers/harness-mcp/repo_agent_harness/serena_gate.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/serena_gate.py)
# Core Harness Tools, Serena Proxy & Workflow Skills
The `repo_agent_harness` package is the stdio MCP server that gives a coding agent repo-aware verbs without owning IDE state. It bundles four capability surfaces: a **tool surface** for foreground edits (`server.py`), a **serena_gate** adapter that brokers calls to the Serena LSP/MCP runtime, a **perception / context** layer (`context.py`, `git.py`) that pushes repo state into the prompt, and a set of **analysis helpers** for symbols and impact (`symbols.py`, `impact.py`). Version drift is currently zero on this plugin (`v3.9.2` matches its manifest) and `repo_bootstrap` is already parametrized.
## Core Harness Tools
`server.py` is the MCP tool registry. The verbs it exposes split into two families: **bootstrap / perception** (`repo_bootstrap`, `repo_state`, `repo_verify_changed`, `repo_health`) and **action** (`repo_apply_patch`, `repo_commit`, `repo_deploy`, plus the harness's deploy validation). The community is currently collapsing the on-demand verbs `repo_verify_changed` and `repo_health` into thin "force a refresh" wrappers over the backgrounded `repo_state` snapshot, because the underlying checks already run in the background daemon. Source: [servers/harness-mcp/repo_agent_harness/server.py:1-1]()
A separate, parallel set of perception upgrades is in flight. CI status will be folded into the same `repo_state` snapshot by reusing `health._ci_check` (a `gh run list` call) on a timed interval, gated per-repo because it is a network call. External edits to files the agent has open will be detected by hashing the paths recorded in `perception_touched.json` and comparing against the watcher; on mismatch, the agent is warned. Both features are scoped in issues #33 and #34 and share the same daemon architecture.
## Serena Proxy (serena_gate)
`serena_gate.py` is a thin adapter — not a full re-implementation of Serena. It exists because the harness is a **stdio MCP server** and the experimental `claude/channel` push transport is unreliable from stdio servers (anthropic/claude-code #45563, #36431), so delivery currently flows through Claude Code hooks rather than server-pushed channels. Source: [servers/harness-mcp/repo_agent_harness/serena_gate.py:1-1]()
The gate translates a small set of harness verbs into Serena RPCs, caches symbol lookups, and surfaces failures as MCP tool errors. Once upstream fixes land, an optional flag-gated `claude/channel` capability will be added behind the same gate so the harness can opt into server-push delivery without restructuring consumers (issue #36).
## Context, Git & Symbol Helpers
`context.py` builds the per-prompt digest that is injected via `UserPromptSubmit`. It currently renders branch, HEAD, merge-conflict status, and is the integration point for the upcoming CI conclusion and touched-set hash digest. `git.py` owns the actual `git` subprocess calls and the backgrounded watcher that feeds `context.py`. Source: [servers/harness-mcp/repo_agent_harness/context.py:1-1](), [servers/harness-mcp/repo_agent_harness/git.py:1-1]()
`symbols.py` wraps the language-server symbol resolution that the serena_gate delegates into, and `impact.py` answers "what does this change break?" questions using those symbols plus the git index. Together they let `repo_apply_patch` preview blast radius before the agent commits a diff. Source: [servers/harness-mcp/repo_agent_harness/symbols.py:1-1](), [servers/harness-mcp/repo_agent_harness/impact.py:1-1]()
## Workflow Skills & Open Work
The harness today surfaces a **deploy tool** whose validation surface is drifted from the deploy plugin's actual contract, which is the motivation behind issue #37 ("De-hardcode the harness deploy tool"). The fix path is parametrization through the existing `repo_bootstrap` parameters rather than a new tool. Skill workflows that wrap `repo_bootstrap → patch → impact → commit → deploy` sit above this layer in the agent harness and are not part of the harness MCP package itself. Source: [servers/harness-mcp/repo_agent_harness/server.py:1-1]()
| Layer | File | Role |
|---|---|---|
| MCP tool registry | `server.py` | Registers verbs, dispatches to helpers |
| Prompt digest | `context.py`, `git.py` | Builds & refreshes the perception snapshot |
| LSP adapter | `serena_gate.py` | Proxies to Serena, gates Channels delivery |
| Analysis | `symbols.py`, `impact.py` | Symbol resolution & blast-radius preview |
The near-term direction is consolidation: one `repo_state` snapshot as the single source of truth, optional Channels capability behind a flag, external-edit detection, and CI status folded into the same digest.
---
## Memory & Perception Layer (cognee ↔ claude-mem)
### Related Pages
Related topics: [Core Harness Tools, Serena Proxy & Workflow Skills](#page-2), [Deployment, Drift Detection & Operations](#page-4)
Related Source Files
The following source files were used to generate this page:
- [servers/harness-mcp/repo_agent_harness/perception.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/perception.py)
- [servers/harness-mcp/repo_agent_harness/watcher.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/watcher.py)
- [servers/harness-mcp/repo_agent_harness/mem.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/mem.py)
- [servers/harness-mcp/repo_agent_harness/cognee_client.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_client.py)
- [servers/harness-mcp/repo_agent_harness/cognee_local.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_local.py)
- [servers/harness-mcp/repo_agent_harness/cognee_sync.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_sync.py)
# Memory & Perception Layer (cognee ↔ claude-mem)
## Purpose and Scope
The harness ships a two-track substrate for stateful operation. The **memory** track persists long-term recall via cognee and mirrors it into claude-mem so both stores stay in agreement. The **perception** track supplies in-band awareness of repository and environment changes (branch/HEAD switches, merge conflicts, CI status, external edits) so the agent doesn't reach for ad‑hoc shell tools.
v3.23.0 formalized the coexistence model behind a flag: writes are mirrored, the legacy on-the-wire client capture path is removed, and recall is gated off by default. The intent is to keep cognee as the canonical store while letting claude-mem serve hot conversational recall, without either side observing duplicate or conflicting state.
Source: [servers/harness-mcp/repo_agent_harness/mem.py]()
Source: [PR #42 — feat(mem): cognee ↔ claude-mem coexistence (v3.23.0)]()
## Memory: cognee ↔ claude-mem Coexistence
### Topology
The cognee side is split into three narrow modules rather than one monolith:
| Module | Role |
|---|---|
| `cognee_client.py` | Network/client boundary to a cognee daemon. Owns request shape and retries. |
| `cognee_local.py` | Local in-process adapter used when no daemon is reachable (CI, air‑gapped). |
| `cognee_sync.py` | Mirror engine — diffs cognee state against claude-mem and reconciles. |
`mem.py` is the **only** entry point agents call. It picks `cognee_client` vs `cognee_local` based on environment, then runs every write through `cognee_sync` so claude-mem observes the same event.
Source: [servers/harness-mcp/repo_agent_harness/mem.py]()
Source: [servers/harness-mcp/repo_agent_harness/cognee_client.py]()
Source: [servers/harness-mcp/repo_agent_harness/cognee_local.py]()
Source: [servers/harness-mcp/repo_agent_harness/cognee_sync.py]()
### What Changed in v3.23.0
Three behaviors were tightened, all reachable through `mem.py`:
1. **Mirror, don't duplicate.** Every recall-bearing write is broadcast to both backends via `cognee_sync`. Cognee remains the system of record; claude-mem is a read-through cache.
2. **Remove client capture.** The earlier design observed transcript text inside the cognee client transport. That capture has been excised so `cognee_client.py` is a pure network shim. Conversation capture is now claude-mem's responsibility.
3. **Gate recall off by default.** Recall is opt‑in via configuration. An agent that hasn't enabled it gets a no‑op `mem.recall`, avoiding surprise context inflation.
```mermaid
flowchart LR
Agent[Agent / Tool call] --> Mem[mem.py facade]
Mem --> Client{cognee daemon reachable?}
Client -- yes --> CC[cognee_client.py]
Client -- no --> CL[cognee_local.py]
CC --> Sync[cognee_sync.py]
CL --> Sync
Sync --> CogDB[(cognee store)]
Sync --> CmDB[(claude-mem store)]
Sync -- gated recall --> Agent
```
Source: [servers/harness-mcp/repo_agent_harness/mem.py]()
Source: [servers/harness-mcp/repo_agent_harness/cognee_sync.py]()
## Perception: Repository Awareness
Perception runs as a background watcher that publishes a `repo_state` snapshot, which downstream surfaces (tool responses, `UserPromptSubmit` digest) consume.
### Watcher Core
`watcher.py` is the filesystem watcher. It consumes the touched-set recorded by `PostToolUse` hooks (typically persisted to `perception_touched.json`) and wakes the perception loop when an interesting change lands — branch switches, HEAD moves, merge‑conflict markers, or external edits to files the agent is currently holding.
Source: [servers/harness-mcp/repo_agent_harness/watcher.py]()
Source: [servers/harness-mcp/repo_agent_harness/perception.py]()
### Snapshot and Tools
`perception.py` owns the periodic rebuild of `repo_state` and exposes the high-level verbs. The design intent — tracked in #35 — is to make `repo_state` the primary surface and demote `repo_verify_changed` / `repo_health` to thin "force a refresh" wrappers, since the daemon already runs the checks in the background.
Source: [issue #35 — consolidate repo_verify_changed + repo_health into repo_state]()
### Known Gaps Tracked as Issues
- **External edits to in-flight files** (#34): hash/mtime the touched‑set; alert when the watcher sees a change the agent didn't author.
- **CI status in the snapshot** (#33): reuse `health._ci_check` on a timed interval (network opt‑in) and surface the latest workflow conclusion in `repo_state` and the `UserPromptSubmit` digest, so the agent stops reaching for `gh` manually.
- **Channels delivery upgrade** (#36): the harness currently falls back to Claude Code hooks because `claude/channel` push is unreliable from stdio MCP servers. The upgrade path is flag-gated and waits on upstream fixes (anthropic/claude-code #45563, #36431).
Source: [issue #34 — detect external edits]()
Source: [issue #33 — fold CI status into the perception snapshot]()
Source: [issue #36 — Channels delivery upgrade]()
## How Memory and Perception Cooperate
A typical agent turn flows through both layers:
1. `Perception` watches the working set and keeps `repo_state` fresh.
2. The agent decides to recall context — `mem.recall` consults claude-mem first, falls back to cognee if needed, and is opt-in only.
3. A write goes through `mem.write`, which dispatches through `cognee_client`/`cognee_local` and is mirrored by `cognee_sync`.
4. On the next perceived repo-state change, perception rebuilds and the cycle continues.
This split — **mem for facts, perception for "what's happening right now"** — is the practical mental model for operating the harness today.
Source: [servers/harness-mcp/repo_agent_harness/mem.py]()
Source: [servers/harness-mcp/repo_agent_harness/perception.py]()
---
## Deployment, Drift Detection & Operations
### Related Pages
Related topics: [Plugin Overview & System Architecture](#page-1), [Memory & Perception Layer (cognee ↔ claude-mem)](#page-3)
Related Source Files
The following source files were used to generate this page:
- [servers/harness-mcp/repo_agent_harness/deploy.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/deploy.py)
- [servers/harness-mcp/repo_agent_harness/drift.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/drift.py)
- [servers/harness-mcp/repo_agent_harness/verify.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/verify.py)
- [servers/harness-mcp/repo_agent_harness/health.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/health.py)
- [servers/harness-mcp/repo_agent_harness/detect.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/detect.py)
- [servers/harness-mcp/repo_agent_harness/policies.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/policies.py)
# Deployment, Drift Detection & Operations
The **Deployment, Drift Detection & Operations** subsystem is the operations backbone of the `repo_agent_harness` MCP server. It defines how the harness plugin is bootstrapped into a repository, how local reality is compared against the declared plugin manifest, how post-deploy sanity checks are executed, and how policy gates decide which operations are allowed. Together these modules form the closed loop that prevents silent version skew between the harness plugin and the consumer-facing deploy surface.
The subsystem is intentionally split into six cooperating modules so that each concern — bootstrap, drift, verification, health, repository detection, and policy — can evolve independently. Community tracking issue **#37 ("T6 — De-hardcode the harness deploy tool")** explicitly notes that `repo_bootstrap` is already parametrized, that the harness plugin has no version drift (v3.9.2 == manifest, 0 unreleased commits), but that the **deploy-validation surface** is drifted versus the deploy plugin's contract. The pages below address each concern in the order an operator typically encounters them.
## Deploy Tooling and Bootstrap
`deploy.py` owns the lifecycle of bringing the harness plugin into a target repository. It exposes a `repo_bootstrap` entry point that, according to the issue context, is "already parametrized," meaning it accepts the target repo path, the plugin version, and the bootstrap mode rather than relying on hard-coded constants. The module is responsible for materializing plugin manifests, writing the harness entry under `.harness/`, and reporting the resolved versions back to the caller for downstream comparison.
`drift.py` is the counterweight to `deploy.py`. Whereas `deploy.py` writes state, `drift.py` reads it back and answers a single question: **does what is on disk still match what the manifest claims?** It compares the deployed plugin version against the manifest version, counts any unreleased commits in the plugin checkout, and emits a structured drift report. Issue **#37** explicitly relies on `drift.py` to certify the harness plugin's "no version drift" property (v3.9.2 == manifest, 0 unreleased commits) before the deploy surface is allowed to advance. This is the primary mechanism by which the project blocks releases whose deploy-validation surface has drifted away from the deploy plugin's contract.
## Verification, Health, and Detection
`verify.py` provides on-demand verification verbs that the agent (and human operators) can invoke to re-run drift and integrity checks synchronously. It typically consumes the output of `drift.py` and adds deeper checks such as file integrity, manifest schema conformance, and the presence of required bootstrap artifacts. Per issue **#35 ("refactor(perception): consolidate repo_verify_changed + repo_health into repo_state")**, the long-term direction is for `repo_verify_changed` to become a thin "force a refresh" wrapper around the continuously running `repo_state` perception snapshot — once the perception daemon is trusted, the on-demand verbs become force-refresh affordances rather than primary surfaces.
`health.py` complements `verify.py` with continuous, polling-style checks: repository reachability, working-tree cleanliness, hook liveness, and — per issue **#33 ("feat(perception): fold CI status into the perception snapshot")** — the `_ci_check` helper that calls `gh run list` to fetch the latest workflow conclusion. The plan is to reuse `_ci_check` on a timed interval so that CI status appears in `repo_state` and in the `UserPromptSubmit` digest, removing the need for the agent to reach for `gh` manually. The `_ci_check` is network-dependent and is therefore gated behind per-repo opt-in.
`detect.py` identifies the repository under the harness's working directory: it infers the owner, remote URL, default branch, and whether the repo is a fork, a worktree, or a submodule. All upstream modules (`drift.py`, `verify.py`, `health.py`) consume the output of `detect.py` so they can scope their work correctly — drift against the right remote, verification against the right working tree, and health probes against the right hooks.
## Policy Gating
`policies.py` is the gatekeeper that decides which deploy, drift, verify, and health operations are permitted in a given context. It evaluates declarative rules — for example, "block `repo_bootstrap` against a dirty working tree" or "require zero drift before `repo_deploy` can proceed" — and returns a structured allow/deny result that the calling tool surfaces to the agent. By centralizing policy, the harness keeps `deploy.py` and `drift.py` free of conditional logic that would otherwise leak across modules.
## Data Flow and Module Boundaries
```mermaid
flowchart LR
A[detect.py
repo introspection] --> B[deploy.py
repo_bootstrap]
A --> C[drift.py
version diff]
B --> C
C --> D[verify.py
on-demand checks]
C --> E[health.py
continuous probes]
P[policies.py] --> B
P --> C
P --> D
P --> E
D --> F[(repo_state
perception snapshot)]
E --> F
```
The flow above reflects the current architecture and the consolidation planned in issue **#35**: `detect.py` seeds context, `deploy.py` writes state, `drift.py` measures skew, and `verify.py`/`health.py` push results into the unified `repo_state` perception surface, all under the supervision of `policies.py`.
## Operational Notes
- The harness plugin is intentionally pinned: the "no version drift" baseline (v3.9.2 == manifest) is the gate that keeps the deploy-validation surface honest, per issue **#37**.
- `_ci_check` in `health.py` is **opt-in per repository** because it requires network access and a configured `gh` CLI.
- As perception matures, `repo_verify_changed` and `repo_health` are expected to become thin wrappers that force-refresh `repo_state` rather than independent verification paths, per issue **#35**.
- Any change to deploy semantics must be paired with a corresponding `drift.py` and `policies.py` update; otherwise the validation surface will silently desynchronize from the deploy surface — the exact failure mode issue **#37** is designed to prevent.
Source: [servers/harness-mcp/repo_agent_harness/deploy.py:1-1](), [servers/harness-mcp/repo_agent_harness/drift.py:1-1](), [servers/harness-mcp/repo_agent_harness/verify.py:1-1](), [servers/harness-mcp/repo_agent_harness/health.py:1-1](), [servers/harness-mcp/repo_agent_harness/detect.py:1-1](), [servers/harness-mcp/repo_agent_harness/policies.py:1-1]()
---
---
## Pitfall Log
Project: astrojones/astrojones-mcp-retrieval
Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.
## 1. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/astrojones/astrojones
## 2. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/astrojones/astrojones
## 3. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones
## 4. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/astrojones/astrojones
## 5. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/astrojones/astrojones
## 6. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/astrojones/astrojones