agent-knowledge-cli 0.1.2__py3-none-any.whl

agent_knowledge/assets/scripts/validate-knowledge.sh

@@ -0,0 +1,265 @@
+#!/bin/bash
+#
+# Validate the project knowledge layout and key operational links.
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENTS_RULES_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/knowledge-common.sh"
+
+usage() {
+    cat <<'EOF'
+Usage:
+  scripts/validate-knowledge.sh [project-dir]
+  scripts/validate-knowledge.sh --project <dir> [--dry-run] [--json] [--summary-file <file>]
+EOF
+}
+
+TARGET_PROJECT_ARG="."
+POSITIONAL=()
+ERRORS=()
+WARNINGS=()
+CHECKS=()
+
+while [ "$#" -gt 0 ]; do
+    if kc_parse_common_flag "$@" ; then
+        shift
+        continue
+    fi
+    flag_status=$?
+    if [ "$flag_status" -eq 2 ]; then
+        shift 2
+        continue
+    fi
+
+    case "$1" in
+        --project)
+            TARGET_PROJECT_ARG="${2:-.}"
+            shift 2
+            ;;
+        *)
+            POSITIONAL+=("$1")
+            shift
+            ;;
+    esac
+done
+
+if [ "$SHOW_HELP" -eq 1 ]; then
+    usage
+    exit 0
+fi
+
+if [ ${#POSITIONAL[@]} -ge 1 ]; then
+    TARGET_PROJECT_ARG="${POSITIONAL[0]}"
+fi
+
+kc_load_project_context "$TARGET_PROJECT_ARG"
+
+check_required_path() {
+    local path="$1"
+    local label="$2"
+    if [ -e "$path" ]; then
+        CHECKS+=("$label:ok")
+    else
+        ERRORS+=("Missing $label at $path")
+    fi
+}
+
+check_required_dir() {
+    local path="$1"
+    local label="$2"
+    if [ -d "$path" ]; then
+        CHECKS+=("$label:ok")
+    else
+        ERRORS+=("Missing directory $label at $path")
+    fi
+}
+
+check_required_path "$AGENT_PROJECT_FILE" ".agent-project.yaml"
+check_required_dir "$KNOWLEDGE_POINTER_PATH" "agent-knowledge local handle"
+check_required_dir "$KNOWLEDGE_REAL_DIR" "real knowledge dir"
+check_required_path "$STATUS_FILE" "STATUS.md"
+check_required_path "$MEMORY_ROOT" "Memory/MEMORY.md"
+check_required_dir "$DECISIONS_DIR" "Memory/decisions"
+check_required_dir "$EVIDENCE_RAW_DIR" "Evidence/raw"
+check_required_dir "$EVIDENCE_IMPORTS_DIR" "Evidence/imports"
+check_required_dir "$SESSIONS_DIR" "Sessions"
+check_required_dir "$OUTPUTS_DIR" "Outputs"
+
+if [ -f "$AGENT_PROJECT_FILE" ]; then
+    for key in name slug pointer_path real_path memory_root evidence_raw evidence_imports; do
+        if [ -z "$(kc_yaml_leaf_value "$AGENT_PROJECT_FILE" "$key" || true)" ]; then
+            ERRORS+=("Missing required .agent-project.yaml key: $key")
+        fi
+    done
+fi
+
+pointer_resolved="$(kc_pointer_resolved_path || true)"
+if [ -z "$pointer_resolved" ]; then
+    ERRORS+=("Unable to resolve ./agent-knowledge as a local handle.")
+elif [ "$pointer_resolved" != "$KNOWLEDGE_REAL_DIR" ]; then
+    ERRORS+=("agent-knowledge resolves to $pointer_resolved but .agent-project.yaml expects $KNOWLEDGE_REAL_DIR")
+elif [ ! -L "$KNOWLEDGE_POINTER_PATH" ]; then
+    if kc_is_windows_like; then
+        WARNINGS+=("agent-knowledge is not reported as a symlink; if this is a junction, verify it still points to the external knowledge folder.")
+    else
+        ERRORS+=("agent-knowledge must be a symlink to the external knowledge folder in canonical mode.")
+    fi
+fi
+
+validate_durable_note() {
+    local file="$1"
+    local rel
+    rel="$(kc_rel_knowledge_path "$file")"
+    local note_type
+
+    note_type="$(kc_yaml_leaf_value "$file" "note_type" || true)"
+    if ! kc_has_frontmatter "$file"; then
+        ERRORS+=("$rel is missing YAML frontmatter")
+        return
+    fi
+
+    case "$note_type" in
+        durable-memory-root|durable-memory-branch|memory-branch|tooling-memory|tooling-index|decision-log)
+            for heading in "## Purpose" "## Current State" "## Recent Changes" "## Decisions" "## Open Questions"; do
+                if ! grep -q "^$heading\$" "$file"; then
+                    ERRORS+=("$rel is missing required section: $heading")
+                fi
+            done
+            ;;
+        structural-evidence|generated-output)
+            for heading in "## Purpose"; do
+                if ! grep -q "^$heading\$" "$file"; then
+                    ERRORS+=("$rel is missing required section: $heading")
+                fi
+            done
+            ;;
+        decision)
+            for heading in "## What" "## Why" "## Alternatives Considered" "## Consequences"; do
+                if ! grep -q "^$heading\$" "$file"; then
+                    ERRORS+=("$rel is missing required section: $heading")
+                fi
+            done
+            ;;
+    esac
+}
+
+check_links() {
+    local file="$1"
+    local rel
+    rel="$(kc_rel_knowledge_path "$file")"
+    local link=""
+    local target=""
+    local base_dir
+    base_dir="$(dirname "$file")"
+
+    while IFS= read -r link; do
+        target="$(printf '%s' "$link" | sed 's/^[^)]*(//; s/)$//')"
+        case "$target" in
+            http:*|https:*|mailto:*|'#'*|'')
+                continue
+                ;;
+        esac
+        if [ ! -e "$base_dir/$target" ]; then
+            WARNINGS+=("Broken-looking link in $rel -> $target")
+        fi
+    done <<EOF
+$(grep -o '\[[^]]*\]([^)]*)' "$file" 2>/dev/null || true)
+EOF
+}
+
+memory_files="$(find "$MEMORY_DIR" -name "*.md" | sort)"
+while IFS= read -r file; do
+    [ -n "$file" ] || continue
+    validate_durable_note "$file"
+done <<EOF
+$memory_files
+EOF
+
+# Check same-name branch convention: folders under Memory/ should have a same-name entry note
+branch_dirs="$(find "$MEMORY_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort)"
+while IFS= read -r branch_dir; do
+    [ -n "$branch_dir" ] || continue
+    branch_name="$(basename "$branch_dir")"
+    entry_note="$branch_dir/$branch_name.md"
+    if [ ! -f "$entry_note" ]; then
+        WARNINGS+=("Branch folder Memory/$branch_name/ is missing its entry note: $branch_name.md")
+    fi
+done <<EOF
+$branch_dirs
+EOF
+
+knowledge_markdown="$(find "$KNOWLEDGE_DIR" -name "*.md" | sort)"
+while IFS= read -r file; do
+    [ -n "$file" ] || continue
+    check_links "$file"
+done <<EOF
+$knowledge_markdown
+EOF
+
+for path in \
+    "$AGENTS_RULES_DIR/scripts/update-knowledge.sh" \
+    "$AGENTS_RULES_DIR/scripts/ship.sh" \
+    "$AGENTS_RULES_DIR/scripts/global-knowledge-sync.sh" \
+    "$AGENTS_RULES_DIR/scripts/graphify-sync.sh" \
+    "$AGENTS_RULES_DIR/scripts/bootstrap-memory-tree.sh" \
+    "$AGENTS_RULES_DIR/scripts/import-agent-history.sh" \
+    "$AGENTS_RULES_DIR/scripts/compact-memory.sh" \
+    "$AGENTS_RULES_DIR/scripts/validate-knowledge.sh" \
+    "$AGENTS_RULES_DIR/scripts/doctor.sh" \
+    "$AGENTS_RULES_DIR/commands/knowledge-sync.md" \
+    "$AGENTS_RULES_DIR/commands/ship.md" \
+    "$AGENTS_RULES_DIR/commands/global-knowledge-sync.md" \
+    "$AGENTS_RULES_DIR/commands/graphify-sync.md" \
+    "$AGENTS_RULES_DIR/commands/doctor.md" \
+    "$AGENTS_RULES_DIR/rules/memory-bootstrap.mdc" \
+    "$AGENTS_RULES_DIR/rules/memory-writeback.mdc" \
+    "$AGENTS_RULES_DIR/rules/history-backfill.mdc" \
+    "$AGENTS_RULES_DIR/rules/workflow-orchestration.mdc"; do
+    [ -e "$path" ] || ERRORS+=("Missing required framework target: $path")
+done
+
+result="ok"
+exit_code=0
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    result="error"
+    exit_code=1
+elif [ ${#WARNINGS[@]} -gt 0 ]; then
+    result="warn"
+fi
+
+kc_status_load
+if [ "${DRY_RUN:-0}" -eq 0 ]; then
+    STATUS_LAST_VALIDATION="$(kc_now_utc)"
+    STATUS_LAST_VALIDATION_RESULT="$result"
+fi
+STATUS_WARNING_LINES="$(printf '%s\n' "${WARNINGS[@]+"${WARNINGS[@]}"}")"
+kc_status_write "$STATUS_WARNING_LINES"
+
+json_summary="{"
+json_summary="$json_summary\"script\":\"validate-knowledge\","
+json_summary="$json_summary\"project_root\":\"$(kc_json_escape "$TARGET_PROJECT")\","
+json_summary="$json_summary\"result\":\"$(kc_json_escape "$result")\","
+json_summary="$json_summary\"dry_run\":$(kc_json_bool "$DRY_RUN"),"
+json_summary="$json_summary\"errors\":$(kc_json_array "${ERRORS[@]+"${ERRORS[@]}"}"),"
+json_summary="$json_summary\"warnings\":$(kc_json_array "${WARNINGS[@]+"${WARNINGS[@]}"}"),"
+json_summary="$json_summary\"checks\":$(kc_json_array "${CHECKS[@]+"${CHECKS[@]}"}")"
+json_summary="$json_summary}"
+kc_write_json_output "$json_summary"
+
+if [ "$JSON_MODE" -ne 1 ]; then
+    kc_log "Knowledge validation: $result"
+    if [ ${#ERRORS[@]} -gt 0 ]; then
+        kc_log "Errors:"
+        printf '  %s\n' "${ERRORS[@]+"${ERRORS[@]}"}"
+    fi
+    if [ ${#WARNINGS[@]} -gt 0 ]; then
+        kc_log "Warnings:"
+        printf '  %s\n' "${WARNINGS[@]+"${WARNINGS[@]}"}"
+    fi
+fi
+
+exit "$exit_code"

agent_knowledge/assets/skills/decision-recording/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: decision-recording
+description: Record architectural and design decisions as lightweight ADRs in agent-knowledge/Memory/decisions/. Use when an important decision is made, reversed, or when the user asks to preserve rationale.
+---
+
+# Decision Recording
+
+Persists the rationale for architectural and design choices so future agents
+do not re-litigate settled questions.
+
+---
+
+## When to record a decision
+
+Record when any of these occur:
+- A technology, framework, or pattern is chosen over alternatives
+- A structural constraint is adopted (e.g., "no ORM", "raw SQL only")
+- A previous decision is reversed or superseded
+- The user says "remember why we chose X" or "note that we decided not to do Y"
+
+Do NOT record:
+- Tactical choices (variable names, minor refactors, formatting)
+- Facts that are obvious from reading the code
+- Speculative decisions not yet confirmed
+
+---
+
+## Step 1 -- Create the decision file
+
+```bash
+SLUG="<short-hyphenated-title>"
+DATE=$(date +%Y-%m-%d)
+FILE="agent-knowledge/Memory/decisions/${DATE}-${SLUG}.md"
+```
+
+Copy from `templates/memory/decision.template.md`.
+Preserve YAML frontmatter.
+
+---
+
+## Step 2 -- Fill in the template
+
+Required fields -- keep each one short:
+
+| Field | Content |
+|-------|---------|
+| **What** | One sentence: what was decided |
+| **Why** | Primary driver: constraint, measurement, user preference |
+| **Alternatives considered** | 1-3 bullets: what was rejected and why |
+| **Consequences** | 1-3 bullets: what this locks in or rules out |
+
+Optional:
+- **Superseded by**: link to the reversal decision if this one is no longer active
+
+---
+
+## Step 3 -- Link from the relevant branch note
+
+In the relevant branch note under `Memory/`, add or update the **Decisions** section:
+
+```markdown
+## Decisions
+- [2025-01-15-use-raw-sql.md](decisions/2025-01-15-use-raw-sql.md) -- chose raw SQL over ORM
+```
+
+One line per decision. Keep descriptions under 10 words.
+
+---
+
+## Step 4 -- Update decisions/decisions.md
+
+Prepend a line in `agent-knowledge/Memory/decisions/decisions.md`:
+
+```markdown
+- [2025-01-15-use-raw-sql.md](2025-01-15-use-raw-sql.md) -- chose raw SQL over ORM
+```
+
+Newest first. If the decision reverses an earlier one, add `[reverses YYYY-MM-DD-slug]`.
+
+---
+
+## Step 5 -- Update Memory/MEMORY.md if the root summary changed
+
+Keep the root note short. Only update it if the project-level decision summary changed.
+
+---
+
+## Reversing a decision
+
+1. Add `Status: reversed` to the original decision file
+2. Add `Superseded by: [new-decision.md](new-decision.md)` to the original
+3. Create a new decision file for the replacement
+4. Update `decisions/decisions.md`: mark the old entry as `~~reversed~~`
+5. Update the branch note's Decisions section to link the new one
+
+---
+
+## Format reference
+
+```markdown
+---
+note_type: decision
+status: active
+date: 2025-01-15
+---
+
+# Decision: use-raw-sql
+
+## What
+Use raw parameterized SQL instead of an ORM for all database access.
+
+## Why
+Need full control over query shape; ORM abstraction adds complexity without benefit
+given the team's SQL proficiency.
+
+## Alternatives considered
+- **Prisma**: rejected -- too much magic, migration model doesn't fit
+- **Drizzle**: rejected -- adds a dependency and type layer we don't need yet
+
+## Consequences
+- All DB access goes through raw SQL + pgtyped-generated types
+- No model layer; query files live in packages/server/src/queries/
+- New contributors must know SQL
+```

agent_knowledge/assets/skills/history-backfill/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: history-backfill
+description: Backfill project memory from existing repo evidence (codebase, docs, configs, git history, tasks, sessions, agent traces). Use when the memory tree is new or sparse and the project has existing history.
+---
+
+# History Backfill
+
+Reads raw evidence from the repo and existing artifacts, then distills stable facts
+into the curated memory tree.
+
+Use this after `project-ontology-bootstrap` when the project has existing history.
+
+---
+
+## Separation rule -- enforced, never relaxed
+
+| Location | What goes here | Who edits it |
+|----------|----------------|--------------|
+| `agent-knowledge/Evidence/raw/` | Direct snapshots from the current repo state | Only the import script |
+| `agent-knowledge/Evidence/imports/` | Imported docs, tasks, sessions, traces, graph exports | Only the import script |
+| `agent-knowledge/Outputs/` | Generated discovery summaries and structural maps | Only scripts or agents treating them as non-canonical outputs |
+| `agent-knowledge/Memory/` | Curated, stable, distilled facts | Only the agent, via writeback rule |
+
+Never write raw evidence into memory. Never treat evidence as authoritative -- it is input for judgment, not truth.
+
+---
+
+## Step 1 -- Collect evidence
+
+Run the import script:
+
+```bash
+scripts/import-agent-history.sh /path/to/project
+```
+
+This creates evidence files under `Evidence/raw/` and `Evidence/imports/`, and
+generated summaries under `Outputs/`.
+
+---
+
+## Step 2 -- Read evidence in priority order
+
+Read these files in order. Each source has different signal quality:
+
+1. **`imports/existing-docs.txt`** -- highest signal. README, CLAUDE.md, AGENTS.md, and project metadata contain curated intent.
+2. **`raw/manifests.txt`** -- authoritative for stack and dependency boundaries.
+3. **`raw/config-files.txt`** -- strongest signal for conventions and tooling.
+4. **`raw/tests.txt`** and **`raw/ci-workflows.txt`** -- how the project proves and ships behavior.
+5. **`raw/structure.txt`** -- actual architecture shape.
+6. **`imports/tasks.txt`** and **`imports/session-files.txt`** -- recurring work areas and unresolved questions.
+7. **`raw/git-log-detail.txt`** and **`raw/git-log.txt`** -- what changed and why.
+8. **`imports/trace-index.txt`** -- supplemental traces only; never canonical truth.
+
+Read confidence labels before trusting a source:
+
+- `EXTRACTED` means direct structural evidence
+- `INFERRED` means a derived summary that still needs review
+- `AMBIGUOUS` means the source may be stale, partial, or wrong
+
+For agent traces and graph summaries: treat them as evidence with lower confidence than direct repo scans. Extract patterns, not individual claims.
+
+---
+
+## Step 3 -- Distill into memory
+
+For each stable fact extracted from evidence:
+
+1. Identify which memory branch it belongs to
+2. Read the current branch note
+3. Place the fact in the correct section:
+   - **Current State**: for verified facts about the project as it is now
+   - **Recent Changes**: for things that changed recently (prune after ~4 weeks)
+   - **Open Questions**: for things the evidence hints at but doesn't resolve
+   - **Decisions**: link to a decision file if it's an architectural choice
+4. Lead with the fact. Do not pad with context the reader can find in git.
+
+If a fact doesn't fit any existing branch, create a new branch note using the
+same-name convention. Use the project's own terminology for the branch name.
+
+---
+
+## Step 4 -- Quality filters
+
+Only write a fact to memory if it passes all of:
+- **Stable**: unlikely to change in the next few weeks
+- **Non-obvious**: not immediately derivable from reading the code
+- **Useful**: would save a future agent meaningful time or prevent a mistake
+- **Verified**: supported by at least one evidence source (not inferred)
+
+Do not write:
+- Commit-level implementation details
+- Speculative interpretations of code intent
+- Facts already in project docs that agents can read directly
+- Anything marked as in-progress or planned (goes in session file until confirmed)
+- Machine-generated summaries unless verified against the repo
+
+---
+
+## Step 5 -- Update Memory/MEMORY.md
+
+After updating branch notes, check that `Memory/MEMORY.md` reflects the new content:
+- Keep the root note short
+- Update branch summaries if their durable state changed
+- Add branch links for any new branches created during backfill
+
+---
+
+## Output checklist
+
+- [ ] Each branch note has populated **Current State** (not just TODO markers)
+- [ ] Any patterns from git log are captured in relevant branch notes
+- [ ] Active decisions found in docs are recorded in `decisions/`
+- [ ] Open questions are listed for anything evidence hints at but doesn't resolve
+- [ ] `Memory/MEMORY.md` reflects the real branch state
+- [ ] No evidence content was written directly into memory files

agent_knowledge/assets/skills/memory-compaction/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: memory-compaction
+description: Compact and prune the memory tree when it grows large or stale. Use when Memory/MEMORY.md grows noisy, branch notes exceed 150 lines, or when explicitly asked to clean up memory.
+---
+
+# Memory Compaction
+
+Reorganizes the memory tree to keep it scannable without losing durable facts.
+
+Run this when `compact-memory.sh` reports warnings, or proactively after dense work periods.
+
+---
+
+## Invariants -- never violate
+
+- Every durable fact must survive compaction (move or merge, never delete)
+- `Memory/MEMORY.md` must stay short and scannable
+- Every branch folder must contain a same-name entry note (`<topic>/<topic>.md`)
+- Evidence files are never touched during compaction
+
+---
+
+## Step 1 -- Audit
+
+Run the report script first:
+
+```bash
+scripts/compact-memory.sh /path/to/project
+```
+
+Note which files are flagged as:
+- `CRITICAL` (>200 lines) -- act immediately
+- `WARNING` (>150 lines) -- split at next opportunity
+- `stub or empty` -- populate or remove
+
+---
+
+## Step 2 -- Prune stale entries
+
+In each branch note, remove or update entries that are:
+
+- **Superseded**: a newer entry contradicts the old one -> remove the old, update the new
+- **Dead reference**: refers to a path, API, or dependency that no longer exists -> remove
+- **Speculation never confirmed**: still marked with "might", "probably", "TODO: verify" -> remove or move to Open Questions
+- **Recent Changes too old**: entries older than ~4 weeks -> move stable facts to Current State, drop transient ones
+
+Do not prune:
+- Gotchas and lessons (even old ones are valuable if the risk still exists)
+- Decision rationale (even for reversed decisions -- mark as `Status: reversed`)
+
+---
+
+## Step 3 -- Split large branch notes
+
+If a branch note exceeds ~150 lines:
+
+1. Identify the dominant sub-topic that makes it large
+2. Promote the branch to a folder if it is still a flat note:
+   - Create `Memory/<topic>/` directory
+   - Move `Memory/<topic>.md` to `Memory/<topic>/<topic>.md`
+3. Create `Memory/<topic>/<subtopic>.md` for the extracted content
+4. Replace the moved section in the entry note with a link:
+   ```markdown
+   See [subtopic.md](subtopic.md) for details.
+   ```
+5. Update `Memory/MEMORY.md` branch link if the path changed
+
+---
+
+## Step 4 -- Merge overlapping thin notes
+
+If two branch notes cover the same ground and together are under ~100 lines:
+
+1. Choose the name that better describes the combined scope
+2. Merge content, resolving any contradictions (newer wins)
+3. Delete the merged file
+4. Update `Memory/MEMORY.md` to remove the deleted entry and update the surviving one
+
+---
+
+## Step 5 -- Compact Memory/MEMORY.md
+
+The root note must be scannable at a glance. Keep:
+
+```markdown
+- one short summary per branch
+- markdown links to the branch notes
+- only the most useful open questions
+```
+
+Remove:
+- Branches with empty files that will not be populated
+- Duplicate entries
+
+Add:
+- Any branch notes that exist but are not yet linked
+
+---
+
+## Step 6 -- Update decisions/decisions.md
+
+Verify every file in `decisions/` is listed in `decisions/decisions.md`.
+Remove entries for deleted decision files.
+Mark superseded decisions with `~~strikethrough~~` or `[reversed]` in the log.
+
+---
+
+## Output checklist
+
+- [ ] `compact-memory.sh` shows no CRITICAL or WARNING flags
+- [ ] `Memory/MEMORY.md` is short and readable
+- [ ] No branch note exceeds 150 lines
+- [ ] All branch notes are linked from `Memory/MEMORY.md`
+- [ ] Every branch folder has a same-name entry note
+- [ ] `decisions/decisions.md` is current