> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/specs/phase41-session04-knowledge-graph-write-path/code-review.md).

# Code Review and Repair Report

**Session ID**: `phase41-session04-knowledge-graph-write-path` **Reviewed**: 2026-07-03 **Base Commit**: `e4b94fee2683dc9618917e6fded6814789a88a46` **Scope**: All changes since the base commit (uncommitted work plus mid-session commits) **Result**: RESOLVED

## Review Surface

**Files reviewed** (all changes since the base commit before this report was created):

* `.spec_system/state.json` - tracked-modified
* `.spec_system/specs/phase41-session04-knowledge-graph-write-path/spec.md` - untracked session artifact
* `.spec_system/specs/phase41-session04-knowledge-graph-write-path/tasks.md` - untracked session artifact
* `.spec_system/specs/phase41-session04-knowledge-graph-write-path/implementation-notes.md` - untracked session artifact
* `scripts/lib/knowledge-graph-admin-bridge.ts` - tracked-modified
* `scripts/lib/__tests__/knowledge-graph-admin-bridge.test.ts` - tracked-modified
* `src/lib/knowledge-graph-admin-types.ts` - tracked-modified
* `src/lib/__tests__/knowledge-graph-admin-types.test.ts` - tracked-modified
* `src/hooks/use-knowledge-graph-admin.ts` - tracked-modified
* `src/hooks/use-knowledge-graph-token.ts` - tracked-modified
* `src/hooks/use-knowledge-graph.ts` - tracked-modified
* `src/hooks/__tests__/use-knowledge-graph-admin.test.tsx` - tracked-modified
* `src/hooks/__tests__/use-knowledge-graph-token.test.tsx` - tracked-modified
* `src/hooks/__tests__/use-knowledge-graph.test.tsx` - tracked-modified
* `src/components/knowledge-graph/knowledge-graph-ingest-card.tsx` - tracked-modified
* `src/components/knowledge-graph/knowledge-graph-grounded-chat.tsx` - tracked-modified
* `src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx` - tracked-modified
* `src/components/knowledge-graph/__tests__/knowledge-graph-grounded-chat.test.tsx` - tracked-modified
* `src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx` - tracked-modified
* `src/components/hermes/chat/chat-composer.tsx` - tracked-modified
* `src/components/hermes/chat/chat-message-list.tsx` - tracked-modified
* `src/components/hermes/chat/command-actions.ts` - tracked-modified
* `src/components/hermes/chat/hermes-chat-tab.tsx` - tracked-modified
* `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` - tracked-modified
* `src/lib/knowledge-graph-home-summary.ts` - tracked-modified
* `src/lib/__tests__/knowledge-graph-home-summary.test.ts` - tracked-modified
* `src/components/home/__tests__/knowledge-graph-section.test.tsx` - tracked-modified
* `src/routes/knowledge-graph.tsx` - tracked-modified
* `src/routes/__tests__/knowledge-graph.test.tsx` - tracked-modified
* `src/routes/__tests__/public-demo-routes.test.tsx` - tracked-modified
* `tests/e2e/knowledge-graph.spec.ts` - tracked-modified

**Inventory commands**: `git status`, `git log --oneline "$BASE"..HEAD`, `git diff "$BASE"`, `git diff --cached "$BASE"`, `git ls-files --others --exclude-standard`

## Findings by Severity

### Critical

* No findings.

### High

* No findings.

### Medium

* `src/hooks/use-knowledge-graph-admin.ts:212` and `src/components/knowledge-graph/knowledge-graph-ingest-card.tsx:110` - Missing Graphify was folded into the single admin capability and card write gate, which blocked remove requests even though the bridge remove path does not invoke Graphify and the session requires registered graph artifacts to remain removable. Fix: split ingest capability from base write capability in the hook, keep Graphify as an ingest-only blocker, add separate ingest/remove gate booleans in the card, and add hook plus rendered-card regression tests. Status: FIXED

### Low

* `src/components/hermes/chat/hermes-chat-tab.tsx:260` - The compact disabled tooltip still used stale "live admin writes" product copy inside the grounded Hermes chat surface. Fix: changed the copy to local write-readiness language and added a test assertion for the disabled compact title. Status: FIXED

## Assumptions and Deliberate Non-Fixes

* Graphify is treated as an ingest dependency, not a remove dependency. Evidence: targeted inspection of `handleRemoveRequest` showed tokenized remove validates the graph ID and registry/path safety but does not run Graphify, while `handleIngestRequest` checks Graphify before running `graphify update`.
* Compatibility references to `HERMES_DASHBOARD_ADMIN` remain in parser/server contracts and tests because the session spec explicitly preserves legacy alias fields during migration.

## Behavior Changes

* When Graphify is missing but local write readiness and the same-run token are present, the UI now blocks project ingest while allowing removal of an active registered graph.
* The embedded Hermes chat compact tooltip now says local write readiness is required instead of live admin writes.

## Validation Repair Addendum

* `src/lib/__tests__/knowledge-graph-home-summary.test.ts` - updated the full-suite home-summary expectation from `Live graph` to the shipped `Live local graph` copy. Review result: RESOLVED; test-only expectation now matches implementation.
* `src/routes/__tests__/public-demo-routes.test.tsx` - updated the public-demo grounded chat expectation from the obsolete demo read-only sentence to the shipped demo/privacy local-chat-send boundary. Review result: RESOLVED; test-only expectation now matches implementation.
* Command/check: `bun run test -- src/lib/__tests__/knowledge-graph-home-summary.test.ts src/routes/__tests__/public-demo-routes.test.tsx`
  * Result: PASS - 2 test files, 6 tests passed after the validation repair.

## Evidence Ledger

\| Check | Command or Inspection | Result | Evidence / Blocker | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------- | -------------- | ------------ | ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------- | | Analyzer | `if [ -d .spec_system/scripts ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash /home/aiwithapex/.codex/plugins/cache/apexdev/apex-spec/2.2.18-codex/skills/apex-spec/scripts/analyze-project.sh --json; fi` | PASS | Current session was `phase41-session04-knowledge-graph-write-path`; monorepo was `false`. | | Inventory | `git status`; `git log --oneline e4b94fee2683dc9618917e6fded6814789a88a46..HEAD`; `git diff --name-status e4b94fee2683dc9618917e6fded6814789a88a46`; `git diff --cached --stat e4b94fee2683dc9618917e6fded6814789a88a46`; `git ls-files --others --exclude-standard` | PASS | No mid-session commits; no staged changes; tracked modifications plus three untracked session files were inventoried. | | Regression tests | `bun run test -- src/hooks/__tests__/use-knowledge-graph-admin.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` | PASS | 3 test files, 62 tests passed after the Graphify/remove and tooltip fixes. | | Focused tests | `bun run test -- scripts/lib/__tests__/knowledge-graph-admin-bridge.test.ts src/lib/__tests__/knowledge-graph-admin-types.test.ts src/hooks/__tests__/use-knowledge-graph-admin.test.tsx src/hooks/__tests__/use-knowledge-graph-token.test.tsx src/hooks/__tests__/use-knowledge-graph.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-grounded-chat.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx src/routes/__tests__/knowledge-graph.test.tsx src/components/home/__tests__/knowledge-graph-section.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` | PASS | 11 test files, 112 tests passed. | | E2E tests | `PLAYWRIGHT_REUSE_EXISTING_SERVER=true bun run test:e2e -- tests/e2e/knowledge-graph.spec.ts` | PASS | 4 Chromium tests passed. The default e2e command was blocked by an already-used local server port before test execution, so the existing server was reused. | | Type checker | `bun run typecheck` | PASS | App TypeScript passed after fixing two stale `gate.canWrite` references found by the first run. | | Script type checker | `bun run typecheck:scripts` | PASS | Script TypeScript passed. | | Linter | `bun run lint` | PASS | ESLint completed without reported issues. | | Formatter | `bunx prettier --check $(git diff --name-only e4b94fee2683dc9618917e6fded6814789a88a46 -- '*.ts' '*.tsx' '*.json')` | PASS | All matched changed TypeScript, TSX, and JSON files use Prettier style. | | Whitespace | `git diff --check e4b94fee2683dc9618917e6fded6814789a88a46` | PASS | No whitespace errors. | | ASCII | `perl -ne 'print "$ARGV:$.:$_" if /[^\x00-\x7F]/' $(git diff --name-only e4b94fee2683dc9618917e6fded6814789a88a46) .spec_system/specs/phase41-session04-knowledge-graph-write-path/spec.md .spec_system/specs/phase41-session04-knowledge-graph-write-path/tasks.md .spec_system/specs/phase41-session04-knowledge-graph-write-path/implementation-notes.md` | PASS | No non-ASCII output. | | LF endings | `grep -Il $'\r' $(git diff --name-only e4b94fee2683dc9618917e6fded6814789a88a46) .spec_system/specs/phase41-session04-knowledge-graph-write-path/spec.md .spec_system/specs/phase41-session04-knowledge-graph-write-path/tasks.md .spec_system/specs/phase41-session04-knowledge-graph-write-path/implementation-notes.md` | PASS | No CRLF files reported. | | Product-surface stale copy | `rg -n "HERMES_DASHBOARD_ADMIN | read-only | local admin gate | admin mode | Admin disabled | Checking admin | admin writes | live admin writes | bridge fallback | Bridge fallback" scripts/lib/knowledge-graph-admin-bridge.ts src/lib/knowledge-graph-admin-types.ts src/hooks/use-knowledge-graph-admin.ts src/hooks/use-knowledge-graph-token.ts src/hooks/use-knowledge-graph.ts src/components/knowledge-graph src/components/hermes/chat src/lib/knowledge-graph-home-summary.ts src/routes/knowledge-graph.tsx tests/e2e/knowledge-graph.spec.ts` | PASS | Remaining hits are compatibility constants, parser/test fixtures, or negative e2e assertions. | | Final diff re-read | `git diff --stat e4b94fee2683dc9618917e6fded6814789a88a46`; targeted `git diff --unified` inspections of bridge, parser, hook, component, chat, route, and tests | PASS | No unresolved review issues found after repairs. |

## Summary

1. Reviewed 29 implementation, test, state, and session-artifact files changed since `e4b94fee2683dc9618917e6fded6814789a88a46`.
2. Found 1 medium behavior issue and 1 low product-copy issue; both were fixed with focused regression coverage.
3. Deliberately preserved `HERMES_DASHBOARD_ADMIN` compatibility fields because the session requires temporary alias support.
4. Evidence passed for focused tests, e2e, lint, format, app typecheck, script typecheck, whitespace, ASCII, LF, stale-copy scan, and final diff reread.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/specs/phase41-session04-knowledge-graph-write-path/code-review.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.