Tracking: product roadmap proposals — enterprise capabilities, developer experience features, and unfiled defects (maintainer triage requested)

[Rontu22]

Tracking issue: product roadmap proposals (enterprise capabilities, developer experience, and unfiled defects)

Summary

This is an umbrella tracking issue consolidating a full product review of Greplica as of v0.1.12 (main @ c6071bc). It contains three parts:

• Part A — Enterprise-grade capabilities: structural features required to take Greplica from a single-user, single-machine tool to a team and organization product.
• Part B — Developer experience features: high-value features for individual developers, independent of any enterprise context.
• Part C — Latent defects: concrete bugs and gaps found by code inspection that have no existing issue filed.

All items below were cross-checked against this repository's issue tracker. Proposals that already have issues are intentionally excluded and listed in the "Relationship to existing issues" section at the bottom, so this issue only contains net-new work.

Request to maintainers

I am aware that not all of these proposals are necessarily in scope for this project, and that judgment belongs to the maintainers. I am requesting a triage verdict per item, not implementation. The full text of every proposal is in this issue body so the review can happen in one place; nothing here requires opening another document.

Since this repository uses Issues without the Discussions tab, the entire review-and-discussion workflow below is designed to run inside the issue tracker only.

Review workflow (issues-only)

This issue follows the standard GitHub tracking-issue pattern, adapted to work without Discussions:

1. Verdicts as comments. For each item in the child issue tracker below, a maintainer records a verdict as a comment on this issue using this template:

   Verdict: <item id, e.g. B3>
   Status: accepted | declined | needs-more-information
   Rationale: <one or two sentences>
   

   One comment may batch multiple verdicts.

2. Accepted items become design-discussion child issues. For any item judged genuine and in scope, a dedicated child issue is opened, titled <item id>: <item title>. Its body starts with Part of #<this issue number>, contains the item's full text from this tracker, and adds a "Decision points" section listing the concrete design questions to settle. That child issue is the discussion thread for the item: alternatives, scoping, and API debate happen there, keeping this tracker navigable. Maintainers (or anyone with triage permission) can create it directly by hovering over the task-list line and using "Convert to issue" / "Create sub-issue"; contributors without that permission create the issue manually and mention it here, and I will keep the tracker line in sync (as the author I can edit this body).

3. Declined items are struck through, never deleted. When a verdict is declined, I will edit the corresponding task-list line to strikethrough (~~...~~) and append the one-line rationale, so the decision and its reasoning remain on the record in the tracker itself.

4. Needs-more-information. I will answer clarifying questions in this thread; the item stays open in the tracker until it receives an accepted or declined verdict.

5. Cross-cutting discussion. Use this issue's comment thread only for prioritization, sequencing, and verdicts. Design discussion for a single proposal belongs on that proposal's child issue once it exists.

6. Completion. A task-list item is checked only when its child issue is closed as completed. This issue stays open until every item has either a checked box, a linked in-progress child issue, or a strikethrough with rationale.

Suggested review order: Part C first (defects are cheap to confirm against the code, and two of them, C1 and C6, are correctness/safety relevant), then Part B (small, self-contained developer features), then Part A (larger direction-setting items that deserve the most discussion time).

Child issue tracker

Part A: enterprise-grade capabilities

• A1. Shared team memory: git-native sync (.greplica/ directory, greplica pull / greplica push) — a drafted design-discussion seed (decision points and open questions) is staged at A1: Shared team memory via git-native sync (.greplica/ directory, greplica pull / push) Rontu22/greplica#3 and can be copied into a child issue here if accepted
• A2. Shared team memory: hosted or self-hostable sync service with org and repo namespaces
• A3. Claim authorship and provenance fields in the schema
• A4. Continuous anchor drift detection with automatic quarantine of stale claims
• A5. Confidence decay and retrieval-feedback reinforcement for claims
• A6. Contradiction detection at proposal-apply time
• A7. Memory review queue (human-in-the-loop approval for auto-memory proposals)
• A8. Secret scrubbing at the ingestion boundary (transcripts and proposals)
• A9. Prompt-injection and memory-poisoning defenses on the write path
• A10. Encryption at rest and an append-only audit log
• A11. Data retention and purge commands
• A12. CI/CD memory producer (GitHub Action: PR ingestion, anchor audit as a check, nightly maintenance)
• A13. Monorepo support: path-scoped subgraphs and cwd-aware retrieval filtering
• A14. Retrieval scale: replace brute-force in-process cosine scan with sqlite-vec or equivalent ANN index
• A15. Opt-in ROI metrics and reporting (retrievals served, estimated tokens saved, memory health)
• A16. Fleet and admin management (centrally distributed org config policy, non-interactive install, doctor --json)
• A17. Backup, restore, and graph import commands

Part B: developer experience features

• B1. greplica remember "<fact>" and greplica forget <claim-id>: a first-class human write path
• B2. Memory history commands: greplica log, greplica show <memory-commit>, greplica revert <memory-commit>
• B3. Background hook worker observability: persisted run log and greplica hook status — a drafted breakout with acceptance criteria and non-goals is staged at B3: Background hook worker observability — persisted run log, hook status command, failure artifact retention Rontu22/greplica#2 and can be copied into a child issue here if accepted
• B4. Background agent cost and model visibility and control
• B5. greplica config set <key> <value>
• B6. greplica uninstall --platform <platform>
• B7. Uniform --json output flag on all read commands
• B8. Query latency fast path: query-embedding cache, --fast BM25-only mode, optional warm daemon
• B9. .greplicaignore support for excluding paths from memory capture and anchoring
• B10. Anchor auto-repair across file renames (graph audit anchors --repair)
• B11. Cross-repo search: greplica search --all-repos "<query>"
• B12. Shell completions and improved empty-state output for graph context
• B13. Onboarding packet profile: human-readable orientation output for new team members
• B14. Temporal queries over memory-commit history

Part C: latent defects (no existing issue filed)

• C1. Silent persistence of empty embeddings on embedBatch length mismatch
• C2. Hook worker swallows all errors with bare catch blocks and deletes run artifacts
• C3. GREPLICA_HOME resolved at call time can silently split memory between environments
• C4. defaultBranch() fabricates main when origin/HEAD is not set
• C5. Orphaned embeddings are never deleted, degrading retrieval over time
• C6. Worker prompt interpolates transcript content unescaped inside a containment tag

---

Part A: Enterprise-grade capabilities

The gap between the current product and an enterprise product is not a list of incremental features. It is three structural leaps: memory must become a team asset (A1-A3), memory must become trustworthy (A4-A11), and value must become measurable (A12-A17). Items are ordered accordingly.

A1. Shared team memory: git-native sync

Problem. All memory lives in a per-user SQLite database under greplicaHome() (libs/config/greplica-home.ts). The entire value of the product evaporates at the machine boundary: an engineer who resolves a subtle constraint builds memory that no teammate's agent will ever see. For a team, the core value proposition is the opposite: the organization's agents get smarter because any one agent learned something.

Proposal. Introduce a repo-committed .greplica/ directory holding the canonical exported graph, with two new commands:

• greplica push: export the local main-scope graph into .greplica/ using the existing deterministic folder export (libs/knowledge-graph/folder-export.ts).
• greplica pull: import .greplica/ content and three-way merge memory commits into the local SQLite replica, using memory_commits.parent_memory_commit_id as the merge ancestry.

Memory then travels with the repository, works air-gapped, is code-reviewable like code (a memory change appears as a diff in a PR), and requires no new infrastructure, procurement, or trust conversation. Conflict policy for the initial version can be conservative: concurrent edits to the same object surface as a merge conflict file for human resolution.

Implementation notes. Most primitives already exist: memory commits with parent pointers, scopes (libs/knowledge-graph/scope.ts), and folder export. The missing pieces are a stable on-disk merge format, an importer (see A17), and id-collision rules.

A2. Shared team memory: sync service

Problem. Git-native sync (A1) covers small teams but does not provide org-level namespaces, access control, or memory that spans repositories.

Proposal. A hosted or self-hostable sync backend to which memory commits stream up and down, with org/repo namespaces, SSO/SAML authentication, and role-based access control. The local SQLite database becomes a cache/replica, preserving the local-first, offline-capable story as a differentiator. This is also the natural home for the commercial model.

Dependencies. A1 (merge semantics), A3 (provenance), A10 (audit log).

A3. Claim authorship and provenance

Problem. Claims are anonymous. The claims table (libs/storage/sqlite/schema.ts) records kind, text, truth, intent, and anchors, but not who or what asserted the claim, when, or from which session. The moment memory is shared (A1/A2) or auto-written (the hook worker), "who asserted this and from what evidence" is the trust model, not optional metadata.

Proposal. Add to claims (and plumb through proposals, libs/knowledge-graph/proposal.ts): author (git identity or platform user), created_by (human vs agent, and which platform), session_ref, created_at, and last_verified_at. Render provenance in graph context output so consuming agents can weigh evidence quality.

A4. Continuous drift detection with automatic quarantine

Problem. greplica graph audit anchors exists and anchor fingerprints (libs/knowledge-graph/code-anchors/fingerprint.ts) detect real code changes while ignoring formatting, but the audit is a manual command. Between audits, retrieval serves code_verified claims whose anchored code has changed. A confidently wrong claim is worse than no claim: the agent plans against a false fact.

Note: existing issues #90 (anchor-drift auto-invalidation) and #91 (content-version tracking) cover parts of the detection story. This proposal is scoped to the pieces those issues do not cover: scheduled/incremental execution and the retrieval-side quarantine state.

Proposal.

• Run the drift audit incrementally on cheap triggers (post-commit hook, session start, CI via A12) rather than on demand only.
• Introduce a claim state (for example stale_pending_reverification) that drifted claims enter automatically. Retrieval either excludes quarantined claims or serves them with an explicit inline warning in the context packet, for example: "Warning: the anchored code has changed since this claim was recorded."
• Re-verification (by an agent or human) either restores the claim, updates it with a supersede, or retires it.

A5. Confidence decay and retrieval-feedback reinforcement

Problem. All claims rank equally regardless of age or demonstrated usefulness. The ranking optimizer (optimize:search-ranking) exists but has no production feedback signal to train on.

Proposal. Add usage counters to claims: times_retrieved, times_confirmed_useful, last_verified_at. Claims that keep being retrieved and re-verified rise in rank; untouched claims decay. Provide a lightweight feedback channel for agents and hooks to report "claim X was used and correct" or "claim X was wrong" after a session, and feed that signal into the existing ranking weight optimization. This creates a data flywheel that improves retrieval quality with usage.

A6. Contradiction detection at proposal-apply time

Problem. Nothing prevents a new claim from contradicting an existing one. Over time the graph accumulates mutually inconsistent facts and stops converging. (Existing issue #114 covers duplicate/near-duplicate detection; contradiction detection is a distinct check with a different resolution path.)

Proposal. During proposal apply, embed each new claim and compare against high-similarity existing claims (top-k by cosine, embeddings already exist in graph_object_embeddings). For candidates above a similarity threshold, run a cheap contradiction check and surface: "this may contradict claim.X; supersede, merge, or reject?" In non-interactive (hook worker) mode, flag the pair for the review queue (A7) instead of blocking.

A7. Memory review queue

Problem. Auto-memory updates (libs/hooks/worker.ts) apply proposals silently from a background agent run. Teams will reasonably require a human checkpoint before agent-written facts become shared truth.

Proposal. An opt-in mode where hook-worker proposals land in a pending state instead of being applied. A reviewer lists pending proposals (greplica proposals list), views a rendered memory diff (commit title, summary, created objects, superseded objects), and approves, edits, or rejects. With git-native sync (A1), the review can also materialize as an ordinary pull request against .greplica/, reusing the team's existing review workflow.

A8. Secret scrubbing at the ingestion boundary

Problem. Session transcripts routinely contain environment dumps, connection strings, tokens, internal hostnames, and pasted stack traces. The current transcript projection (libs/session-transcript/) filters to text messages, which is a good start but is not a redaction guarantee. A credential persisted into a claim would then be served into every future agent context.

Proposal. Run secret detection (pattern rules plus entropy heuristics, in the style of gitleaks) on transcript bundles before persistence and on proposal text before proposal apply. Refuse to store claims containing detected live credentials. Make the scrubbing auditable: report "N candidate secrets redacted from session X" in command output and the audit log (A10).

A9. Prompt-injection and memory-poisoning defenses on the write path

Problem. The worker prompt already instructs the agent to treat transcripts as evidence rather than instructions, which is the right instinct but is an instruction-level defense only. Memory poisoning is the novel attack surface of this product category: a malicious string embedded in a PR description, issue, or pasted content can attempt to write itself into memory and thereby into every future agent's context.

Proposal. Add structural defenses:

• Run the memory-update agent with a minimal tool allowlist.
• Extend proposal validation (libs/knowledge-graph/validate-proposal.ts) with policy checks: reject or flag claims containing URLs to unknown domains, imperative instruction-shaped text (for example "always run ..."), or encoded blobs, unless explicitly approved.
• Require the review queue (A7) for any proposal derived from third-party content (external PRs, issues).

Documenting a concrete answer to memory poisoning is itself a differentiator.

A10. Encryption at rest and an append-only audit log

Problem. The SQLite database is plaintext on disk and there is no record of reads or writes. Security review processes (SOC 2 and equivalents) will ask about both.

Proposal. Support SQLCipher or an OS-keychain-wrapped key for the local database as an opt-in configuration. Add an append-only audit table recording who or what read (graph context, graph read) and wrote (proposal apply) memory, with timestamps and session refs.

A11. Data retention and purge commands

Problem. There is no way to remove memory derived from a specific session or time range. Legal and compliance teams require deletion capabilities.

Proposal. greplica purge --session <ref>, greplica purge --before <date>, and greplica purge --source-kind session, each cascading correctly through claims, edges, sources, memberships, and embeddings, with a dry-run flag that prints what would be removed.

A12. CI/CD memory producer (GitHub Action)

Problem. Memory freshness currently depends entirely on individual developers' sessions. Merged-PR discussions, the highest-density decision record in most organizations, are discarded. The repository already contains collection scripts (memory:collect-github, memory:prepare-github-packets) but they are internal build tooling, not a product surface.

Proposal. Ship an official GitHub Action (and a GitLab CI template) that:

• On PR merge: extracts durable decisions from the PR description, review threads, and diff into a proposal, applied directly or queued for review (A7).
• On every PR: runs the anchor audit and reports "this PR breaks or drifts N memory anchors" as a check, which both keeps memory fresh and makes the memory system visible to the whole team.
• Nightly: runs the drift audit (A4), decay pass (A5), and contradiction sweep (A6), publishing a summary report.

This addresses cold start, staleness, and team-level adoption with one artifact.

A13. Monorepo support: path-scoped subgraphs

Problem. The graph_scopes table supports several scope kinds, but the product effectively operates one scope per repo. In a monorepo, memory about apps/checkout is noise for an agent working in libs/design-system, and retrieval quality degrades as the graph grows. (Existing issue #20 covers branch-awareness; path scoping is a separate axis.)

Proposal. Allow scopes bound to repository subpaths. graph context filters or boosts by the agent's working directory. Additionally support org-level claims that apply across repositories (for example, "service X must never be called directly"), which becomes meaningful once A2 exists.

A14. Retrieval scale: ANN index

Problem. scoreSemantic in libs/knowledge-graph/graph-context/context-builder.ts loads every embedding row for the repo into JavaScript and computes cosine similarity in a linear scan per query. This is fine at hundreds of objects; a year of team-wide auto-capture on a monorepo is a graph of tens or hundreds of thousands of objects, at which point every query pays an O(n) load-and-scan.

Proposal. Move vector scoring into the database via sqlite-vec (preserving the zero-server, local-first story) with a fallback to the current scan when the extension is unavailable. Benchmark at 1k/10k/100k objects and publish the results.

A15. Opt-in ROI metrics and reporting

Problem. The README documents 40-75 percent token savings on benchmark cases, but a team cannot measure savings on its own repositories, and adoption and renewal decisions require exactly that evidence.

Proposal. Opt-in, local-first metrics: retrievals served, claims injected per session, estimated tokens and exploration saved (reusing the SWE-chat eval methodology in evals/swechat-plan/), memory health ratios (fresh vs stale vs broken-anchor), and coverage (percentage of sessions that queried memory). Render in the existing graph view HTML or a dedicated report command. No data leaves the machine unless explicitly exported.

A16. Fleet and admin management

Problem. Configuration is per-machine JSON (~/.greplica/config.json). An organization rolling Greplica out to hundreds of engineers needs central policy and unattended installation.

Proposal.

• An org-level policy file (distributed via MDM, dotfiles, or the sync service) that pins embedding provider (many organizations will mandate local-only; others will want Azure OpenAI or Bedrock as additional embedder backends), auto-memory behavior, and retention rules, with local config unable to override pinned keys.
• Fully non-interactive greplica install suitable for scripted rollout.
• greplica doctor --json for fleet health monitoring.

A17. Backup, restore, and import

Problem. graph export <dir> exists, but there is no import, so export is not a usable backup. Database loss means total memory loss.

Proposal. greplica graph import <dir> as the inverse of export (also a dependency of A1), plus greplica backup create / greplica backup restore for whole-database snapshots with schema-version checks against the existing migration machinery (libs/storage/sqlite/migrate.ts).

---

Part B: Developer experience features

Today Greplica is agent-facing at both ends: agents write via proposal JSON and agents read via context packets, while the human is an administrator who edits config JSON by hand. The through-line of this section is making the developer a first-class user of their own memory: able to add to it, see it change, trust it, and remove it cleanly.

B1. greplica remember and greplica forget: a human write path

Problem. The only write path is a proposal JSON file passed to proposal validate / proposal apply, a format designed for agents. A developer who just learned "the flaky checkout test is caused by the shared Redis fixture" has no way to store that fact in under a minute; they would need to hand-craft JSON with ids, kinds, truth levels, and edge definitions.

Proposal.

greplica remember "The flaky checkout test is caused by the shared Redis fixture" \
  --anchor tests/fixtures/redis.ts --kind fact
greplica forget <claim-id>

remember builds and applies a single-claim proposal internally: auto-generated id/slug, default truth: source_verified (upgraded to code_verified when an anchor is provided and fingerprints successfully), optional --about <component-id>. forget retires a single claim (supersede-with-tombstone or removal), distinct from bulk pruning (existing issue #24). This one command changes the product from "a thing my agent uses" to "a thing I use," which is what makes a developer tool sticky.

B2. Memory history: greplica log, show, revert

Problem. The schema records full commit history (memory_commits with parent_memory_commit_id, titles, summaries, timestamps) and proposal apply prints the new commit id, but no command exposes history. A developer cannot answer "what did the background agent write to memory yesterday?" This is compounded by auto-memory updates writing silently.

Proposal.

• greplica log [--limit N]: memory commits newest-first with title, date, and object counts.
• greplica show <memory-commit-id>: the objects that commit created and any superseded objects, analogous to git show.
• greplica revert <memory-commit-id>: undo a single commit; the parent-pointer chain makes this tractable. Reverting is also the safety valve that makes auto-memory updates acceptable to skeptical users.

B3. Background hook worker observability

Problem. In libs/hooks/worker.ts, both startHookWorker() and maybeUpdateWorkingMemory() swallow every error with bare catch blocks, and the run directory (including the agent's final-message.md and event log) is deleted in a finally block. If auto-memory updates have been broken on a machine for a month (bad PATH, missing API key, renamed agent binary), the developer has no way to discover it. The background loop is the product's flywheel; when it fails silently, the product silently stops working while appearing installed.

Proposal.

• Persist the last N worker run outcomes (start/end time, platform, session ref, success/failure, error text, whether a proposal was applied and its commit id) in a hook_worker_runs table or a rotating log under the Greplica home directory.
• greplica hook status: last run per repo, pending sessions awaiting update, last error.
• Surface the same in greplica doctor output, for example: "auto-memory worker: last succeeded 3 days ago; last failure: ...".

B4. Background agent cost and model control

Problem. runWorkingMemoryUpdate spawns a full agent session (Codex, Claude Code, etc.) after coding sessions. This consumes real tokens on the developer's account, silently, with no visibility or bound. libs/agent-runner/metrics.ts already computes usage metrics for evals but is not wired into the worker.

Proposal.

• Record tokens and wall-clock duration per background run; display in hook status (B3).
• A config knob selecting the model used for background updates (memory extraction tolerates a cheaper model than interactive coding).
• Per-repo override of session.autoMemoryUpdates, so a developer can enable auto-updates on their main project without enabling them on every cloned throwaway repo.

B5. greplica config set <key> <value>

Problem. greplica config is print-only. Changing session.stopThreshold or disabling auto-updates requires hand-editing ~/.greplica/config.json against an undocumented schema, with a hard error on any typo (strict parsing in libs/config/greplica-config.ts).

Proposal. greplica config set session.autoMemoryUpdates false, greplica config get <key>, and greplica config unset <key>, validating through the existing normalization functions so invalid values are rejected with the same messages the parser produces today.

B6. greplica uninstall

Problem. Installers write hooks and skills into agent home configuration across seven platforms (libs/install/platforms/): ~/.claude, ~/.codex, ~/.copilot, repo-local .openhands/, and so on. There is no uninstall; removal means manual surgery on files the user did not create. Clean try-and-remove is a precondition for developers being willing to try a tool that hooks into their agent runtime at all.

Proposal. greplica uninstall --platform <platform> [--purge-data]. Each installer already knows exactly what it writes; add the inverse operation to the installer interface. --purge-data additionally removes the repo's rows from the local database (reusing A11 plumbing). Without --purge-data, memory is preserved for a later reinstall.

B7. Uniform --json output

Problem. graph read, doctor, graph audit anchors, and proposal validate print human-oriented prose only (graph context --debug is the lone JSON surface). Developers script CLIs and agents parse them; neither can consume the current output reliably.

Proposal. A --json flag on every read command, emitting the already-structured data that exists immediately before the console.log formatting layer in apps/cli/main.ts. This is low-cost and unlocks shell scripting, CI checks on audit output, editor extensions, and third-party tooling.

B8. Query latency fast path

Problem. Every graph context invocation pays Node cold start, better-sqlite3 load, loading the all-mpnet-base-v2 transformer via @huggingface/transformers, and tree-sitter WASM initialization for anchor resolution, plausibly several seconds before ranking begins. Agents are instructed to query before every task and hooks encourage repeated queries. An agent that waits five seconds per memory query starts skipping memory queries; latency is adoption.

Proposal. In ascending effort:

1. Cache query embeddings (query-hash to vector) in SQLite so repeated queries skip embedding.
2. --fast mode that ranks with BM25 only (no embedder load); the hybrid ranker in context-builder.ts already computes BM25 independently.
3. greplica daemon: a small local process holding the model warm behind a unix socket; the CLI transparently uses it when alive and falls back to in-process execution otherwise. This is the path to sub-200ms retrieval.

B9. .greplicaignore

Problem. Bootstrap and session updates may store facts about, and anchor into, any path in the repository. Developers want to exclude vendored code, generated output, or sensitive directories from memory capture, for both noise and privacy reasons.

Proposal. A repo-root .greplicaignore (gitignore syntax) honored by: the bootstrap skills' inspection guidance, anchor resolution (code-anchors/resolver.ts), and proposal validation (a claim anchored into an ignored path is rejected with a clear message). Document the interaction with existing skill-level skip rules.

B10. Anchor auto-repair across file renames

Problem. Existing issues #90 and #91 cover detecting drift and invalidation, but nothing covers repair. When src/auth/session.ts moves to src/auth/session/index.ts, every anchor into it breaks, and the current answer is that the audit reports breakage and a human or agent rewrites claims. Anchors are the product's differentiator, so anchor durability is disproportionately valuable.

Proposal. greplica graph audit anchors --repair: for each missing_file anchor, consult git rename detection (git log --follow, similarity index) to find the file's new path, re-resolve the symbol there, and update the anchor in place when the re-fingerprinted signature matches the stored baseline (unchanged code, moved location). Ambiguous or signature-changed cases are reported, not auto-repaired. This turns a whole class of memory rot into a non-event.

B11. Cross-repo search

Problem. The database already holds every repo's memory in one SQLite file keyed by repo_id, but queries are bound to the current repo. A developer who remembers "I solved this websocket reconnect problem somewhere last year" must cd into each repo and query separately.

Proposal. greplica search --all-repos "<query>" ranking across all repos with results labeled by repo name and path. Read-only, no scope mutation. Note the interaction with per-repo embedding provider settings: repos embedded with different providers/models rank in separate spaces and should be grouped accordingly in output.

B12. Shell completions and empty-state output

Problem. No completions exist, and graph context on a repo without memory returns an empty ranking that agents can misread as "nothing relevant exists in this codebase" rather than "memory has not been bootstrapped."

Proposal.

• greplica completions zsh|bash|fish, generated from the declarative command table in apps/cli/main.ts.
• When the graph is empty or the query matches nothing, return an explicit short packet: "No memory recorded for this query. If the repository has never been bootstrapped, run the greplica-bootstrap skill." This gives agents a correct next action instead of a silent miss.

B13. Onboarding packet profile

Problem. The graph contains exactly the content a new team member needs (repo identity, subsystem boundaries, decisions, gotchas), but the only human-facing rendering is the graph visualization.

Proposal. greplica graph context --profile onboarding (or greplica onboard): a curated, human-readable orientation document generated from components, flows, and high-confidence decision claims, ordered for reading rather than for agent injection. This turns agent memory into a people-onboarding artifact at near-zero marginal cost.

B14. Temporal queries

Problem. Memory commits give the graph a full time dimension, but it is not queryable. "What did we believe about auth before the v2 migration?" is unanswerable today.

Proposal. greplica graph read --at <date|memory-commit> and a --since/--until filter on log (B2), reconstructing graph membership as of a point in the commit chain. Read-only; no changes to the write path.

---

Part C: Latent defects (found by code inspection; no existing issue)

C1. Silent persistence of empty embeddings

Location. libs/knowledge-graph/graph-context/context-builder.ts, ensureEmbeddings, float32ArrayToBuffer(vectors[index] ?? []).

Defect. If embedBatch ever returns fewer vectors than input documents (provider partial failure, batch truncation), the fallback ?? [] persists a zero-length embedding permanently. That object then silently scores as garbage in every future semantic ranking, with no error at write or read time.

Fix. Throw when vectors.length !== missing.length instead of defaulting, so a partial provider failure is loud and nothing corrupt is persisted.

C2. Hook worker error black hole

Location. libs/hooks/worker.ts: startHookWorker catch block, maybeUpdateWorkingMemory catch block, and the finally that removes the run directory.

Defect. Every failure mode of the background update pipeline, including "node binary not found" and total agent failure, is invisible: errors are swallowed and the artifacts that would explain the failure (final-message.md, agent-events.jsonl) are deleted. This is the defect half of proposal B3; even before B3 ships, failures should at minimum be written somewhere durable.

Fix. Write failure records (timestamp, session ref, error) to a log under the Greplica home directory; retain run artifacts on failure (with a size/age cap) instead of unconditionally deleting them.

C3. GREPLICA_HOME environment split

Location. libs/config/greplica-home.ts; every config, database, and model-cache path resolves through greplicaHome() at call time.

Defect. A hook fired with a different environment than the interactive shell (common when agent apps are GUI-launched and do not inherit shell environment) silently reads and writes a different memory store. The user observes memory "randomly missing" with no diagnostic.

Fix. greplica doctor (and hook status, once B3 exists) should print the resolved home, config path, and database path in effect; hook-injected guidance should pin the resolved home explicitly so foreground and background invocations agree.

C4. defaultBranch() fabricates main

Location. apps/cli/repo-context.ts, defaultBranch.

Defect. When refs/remotes/origin/HEAD is not set (typical for fresh clones and many CI checkouts), the function silently returns "main" even for repositories whose default branch is master or develop, and this value is persisted in the repos table. Harmless today, but it becomes a live correctness bug the moment branch-aware memory (existing issue #20) lands and scoping decisions key off the recorded default branch.

Fix. Try git remote show origin or git ls-remote --symref origin HEAD as fallbacks; if still unknown, store null/unknown rather than a fabricated value, and let consumers handle unknown explicitly.

C5. Orphaned embeddings are never deleted

Location. libs/storage/sqlite/schema.ts (graph_object_embeddings), writes in context-builder.ts.

Defect. Embedding rows are only ever inserted, never deleted, including for objects that are superseded or otherwise retired. Combined with loadEmbeddings reading every row for the repo into memory per query, retrieval cost grows with all objects ever created rather than with live objects. Existing issue #24 (graph pruning) does not mention embedding cleanup; even with pruning, nothing cascades embeddings today because the embeddings table has no foreign key to the object tables.

Fix. Delete embedding rows when their object is removed or superseded; add a greplica gc sweep (or fold into #24) that removes embedding rows with no corresponding live object; long-term, restrict the per-query load to live-object keys (also mitigated by A14).

C6. Unescaped transcript interpolation inside a containment tag

Location. libs/hooks/worker.ts, updateWorkingMemoryPrompt, the <filtered_session_transcript> block.

Defect. The transcript markdown is interpolated verbatim between <filtered_session_transcript> tags. A transcript containing the literal string </filtered_session_transcript> (easy to produce, for example a session that discusses this very code) terminates the containment block early, after which transcript content sits outside the "treat as evidence data, not instructions" framing that the prompt's safety rules rely on. This weakens the write-path injection posture (related to A9 but independently fixable).

Fix. Escape or neutralize the closing-tag sequence in transcript content before interpolation (or use a randomized/nonce-delimited fence), and have the prompt reference the exact fence used.

---

Suggested sequencing

Highest-leverage five, in order:

1. A1 (git-native shared memory): converts a personal tool into a team product with zero infrastructure.
2. A3 + A4 + B2 (provenance, drift quarantine, history/revert): makes shared and auto-written memory trustworthy.
3. B3 + C2 (worker observability): a silently broken flywheel is worse than none.
4. B1 (remember/forget): gives humans a daily reason to touch the tool.
5. A12 (CI/CD Action): freshness, cold start, and team visibility in one artifact.

Relationship to existing issues (excluded from this proposal)

The following areas were deliberately excluded because existing issues in this tracker already cover them: MCP server integration (#25), duplicate/near-duplicate claim detection (#114), anchor-drift auto-invalidation and content-version tracking (#90, #91), graph cleanup and pruning (#24), promote-to-main-scope command (#22), branch-aware memory (#20), graph object lookup commands (#36), platform installs for Cursor (#42) and Cline (#39), graph visualization export (#38), testing surface (#84), database connection lifecycle (#83), standalone-source scoping (#134), transcript-bundle platform gaps (#120), and documentation sync (#129, #126, #80). Where a proposal above touches the same area (A4 vs #90/#91, A6 vs #114, A13 vs #20, C5 vs #24), the text states the precise boundary.

---

Review baseline: v0.1.12, main branch commit c6071bc. File references use repository-relative paths at that commit.

[aadivyaraushan]

Claiming Part C items for contribution PRs:

• C1, C4, C6 — correctness PR (fix/part-c-correctness-c1-c4-c6)
• C2, C3 — hook/runtime PR (fix/part-c-hook-runtime-c2-c3)

Explicitly not claiming C5 (owned by open #108). Skipping anything that touches #108’s gc/embeddings delete path.

[aadivyaraushan]

Contribution update — Part C (latent defects)

Working on the Part C items from this tracking issue (explicitly not C5 / #108). Two PRs:

Part C item	PR	What it does
C1 Silent empty embeddings on embedBatch length mismatch	#173	Reject short/empty/wrong-dimension batches before insert; no zero-length BLOBs
C4 defaultBranch() fabricates main	#173	Prefer origin/HEAD, then ls-remote --symref with a 5s timeout, else "unknown"; reuse/rename existing main scope on re-init (no orphan scopes)
C6 Transcript unescaped in containment tag	#173	Escape literal </filtered_session_transcript> so pasted content cannot break the evidence fence
C2 Hook worker swallows errors / deletes artifacts	#174	Append failures to $GREPLICA_HOME/logs/hook-worker.jsonl (rotated), retain capped copies under logs/runs/, then clean OS temp run dirs
C3 GREPLICA_HOME resolved at call time	#174	resolveGreplicaHome() + pin into hook/agent child env; greplica doctor prints home path/source even when repo is not detected

Merge note

#174 includes a merge of #173 so libs/hooks/worker.ts and package.json keep both the C6 escape and the C2/C3 logging/pin changes. Suggested land order: #173 then #174 (or #174 alone if you prefer one combined landing).

Out of scope here

• C5 (orphaned embeddings lifecycle) — left to feat: add greplica graph gc to prune stale knowledge-graph memory #108 / graph gc work
• Part A / Part B roadmap items — not in these PRs