From 06166dea34c626c9658fd677b073b1f222f4cdfe Mon Sep 17 00:00:00 2001 From: Willi Budzinski Date: Thu, 18 Jun 2026 21:38:33 +0200 Subject: [PATCH 1/2] docs: clarify graph extraction lifecycle on site --- .../plan.md | 84 +++++++++++++++++++ .../todo.md | 82 ++++++++++++++++++ website/components/Features.tsx | 2 +- 3 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/plan.md create mode 100644 docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md diff --git a/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/plan.md b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/plan.md new file mode 100644 index 000000000..5db5e48b3 --- /dev/null +++ b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/plan.md @@ -0,0 +1,84 @@ +# Issue 494 Graph Extraction Lifecycle Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Correct the website Knowledge Graph feature copy so it reflects the current graph extraction lifecycle. + +**Architecture:** This is a website documentation change only. The existing landing page reads generated metadata through `website/lib/meta.ts` and renders feature-card copy from `website/components/Features.tsx`; no runtime memory pipeline code should change. + +**Tech Stack:** Next.js website under `website/`, TypeScript/React, pnpm 11 via Corepack. + +--- + +## Files + +- Modify: `website/components/Features.tsx` +- Update task notes only: `docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md` +- Do not modify runtime source, API handlers, MCP tools, package manifests, lockfiles, or upstream remote configuration. + +## Task 1: Validate And Patch Website Copy + +**Files:** +- Modify: `website/components/Features.tsx` +- Modify: `docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md` + +- [ ] **Step 1: Confirm the stale copy** + +Run: + +```bash +rg -n "Entities and relations extracted on compress|Stop / SessionEnd|graph/build|Knowledge graph extraction" website README.md -S +``` + +Expected: `website/components/Features.tsx` contains the stale "extracted on compress" text, and `README.md` shows the current `Stop / SessionEnd` lifecycle. + +- [ ] **Step 2: Update the Knowledge Graph feature text** + +In `website/components/Features.tsx`, replace the Knowledge Graph `text` value with: + +```tsx + "Entities and relations extract after Stop / SessionEnd, with /agentmemory/graph/build for viewer backfills. Query /agentmemory/graph for temporal edges.", +``` + +This keeps the feature card compact while covering the two Issue #494 lifecycle points that apply locally. + +- [ ] **Step 3: Review the focused diff** + +Run: + +```bash +git diff -- website/components/Features.tsx docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md +``` + +Expected: only the feature-card copy and task-state progress notes changed. + +- [ ] **Step 4: Run focused verification** + +Run: + +```bash +git diff --check +corepack pnpm --dir website run gen-meta +corepack pnpm --dir website exec tsc --noEmit +corepack pnpm --dir website run build +``` + +Expected: all commands exit 0. If `gen-meta` or `build` updates `website/lib/generated-meta.json` only because of `generatedAt` or unrelated version/count metadata, discard that file from the task diff. Any intentional metadata refresh must be split into a separate task or explicitly added to this scope before keeping it. + +- [ ] **Step 5: Run PR-prep safety gates and commit** + +After the branch diff is stable, follow `github-push-prepare` for `origin/main`: fetch `origin main`, inspect branch diff, run required review/security gates for the docs-only surface, stage only task-owned paths, run staged Gitleaks, and commit with: + +```bash +git commit -m "docs: clarify graph extraction lifecycle on site" +``` + +Expected: one scoped docs commit ready for PR to `origin/main`. + +## Self-Review + +Spec coverage: The plan covers Issue #494's local valid surface: website copy says graph extraction runs on compression, while repo docs say it runs after `Stop / SessionEnd` and graph backfill exists at `/agentmemory/graph/build`. + +Placeholder scan: No placeholders, TBDs, or broad "add tests" steps remain. + +Type consistency: The only code-adjacent change is a string literal in an existing React component; no type or API changes are planned. diff --git a/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md new file mode 100644 index 000000000..8b04f6936 --- /dev/null +++ b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md @@ -0,0 +1,82 @@ +# Issue 494 Graph Extraction Lifecycle + +Repository: `/Users/A1538552/.codex/worktrees/f30d/agentmemory` +Branch: `github-pr/issue-494-graph-lifecycle-a029b7e` +Owning scope: `website/` landing page documentation copy, with task-local notes under this directory. +GitHub target: `origin/main` + +## Sprint Contract + +Goal: Resolve Issue #494 by deciding whether the website still misstates the knowledge graph extraction lifecycle and, if valid, applying the smallest documentation update. + +Scope: +- Inspect Issue #494 and local website/docs source. +- Update only website copy that says graph extraction runs on compression if local evidence shows it is stale. +- Run focused website/docs checks and required local safety gates for the changed surface. +- Prepare the branch for a PR to `origin/main`; push, open PR, observe CI, merge, and close/archive only under the user's current-turn authorization. + +Non-goals: +- No runtime, API, schema, MCP, REST endpoint, hook, persistence, dependency, or generated broad metadata change. +- No PR to `upstream` or `rohitg00/agentmemory`. +- No import of the stale upstream PR because Issue #494 records it as closed, unmerged, with zero changed files and zero commits. + +Acceptance criteria: +- Website Knowledge Graph feature copy states graph extraction runs after `Stop` / `SessionEnd`, not generic compression. +- Copy mentions the `/agentmemory/graph/build` backfill path if it fits the existing feature-card length. +- No code/API behavior changes are introduced. +- Relevant checks pass or blockers are recorded with evidence. +- Issue/PR state changes use only `origin` and target `main`. + +Intended verification: +- `git diff --check` +- `corepack pnpm --dir website run gen-meta` +- `corepack pnpm --dir website exec tsc --noEmit` +- `corepack pnpm --dir website run build` +- Required security/secret gates before commit/PR as applicable: Semgrep for agent workflow/docs surface only if config/tool available and staged Gitleaks before commit. + +Known boundaries: +- `gh issue view` is read-only inspection; issue close, push, PR create, PR merge, and thread archive are remote/app state changes covered by the delegated current-turn request. +- Preserve unrelated local work; initial `git status -sb --untracked-files=all` showed no local changes. + +Stop conditions: +- Any required verification fails for reasons unrelated to the docs copy and no targeted substitute proves the changed surface. +- A fix requires runtime/API/schema/dependency/auth/security behavior. +- Remote push/PR/merge requires force-push, history rewrite, or a PR target other than `origin/main`. + +## Feature / Verification Matrix + +| Change | Verification method | Status | Evidence | +|---|---|---|---| +| Validate Issue #494 | Issue view plus local website/README source inspection | In progress | Issue body records upstream PR 727 closed/unmerged with zero files/commits; local `website/components/Features.tsx` still says "Entities and relations extracted on compress." | +| Update website copy | Focused diff review and website build/type checks | Complete | `website/components/Features.tsx` now says graph extraction runs after `Stop / SessionEnd`, names `/agentmemory/graph/build` backfill, and uses the real query route `/agentmemory/graph/query`. | +| PR readiness and safety gates | GitHub push prepare workflow, secret/security scans, origin/main base refresh | In progress | `origin/main` refreshed to `a029b7e`; no base merge needed before commit. Targeted Semgrep passed with 0 findings. Staged Gitleaks passed with no leaks. | +| Remote PR lifecycle | Push branch, create PR to `origin/main`, observe CI, merge when green | Pending | Pending after local verification. | + +## Subagent Ledger + +| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk | +|---|---|---:|---|---|---| +| Read-only Explorer/Evaluator | Issue #494 and website/docs source | No | Decide valid/stale/duplicate/already fixed with file/line evidence | Running | Main agent will verify evidence directly before relying on it. | +| Read-only Plan Reviewer | Task plan and scope | No | Identify High/Medium plan gaps before implementation | Medium finding accepted: tighten handling of generated metadata churn. | Metadata changes stay out of scope unless explicitly split or approved. | + +## Progress Notes + +- 2026-06-18: Read `github-feature-loop`, `writing-plans`, `review-and-implement`, `verification-before-completion`, `github-push-prepare`, `subagent-driven-development`, and repo `AGENTS.md`. +- 2026-06-18: Initial repo state: detached `HEAD` at `a029b7e`, no local changes, remotes are `origin` and `upstream`; user explicitly restricted target to our `origin/main`. +- 2026-06-18: Created branch `github-pr/issue-494-graph-lifecycle-a029b7e` from detached HEAD before edits. +- 2026-06-18: Read-only Explorer confirmed Issue #494 is still valid for website copy: `website/components/Features.tsx` says graph extraction runs "on compress"; README documents `Stop / SessionEnd` graph extraction. +- 2026-06-18: Plan review found metadata churn risk from `website/lib/generated-meta.json`; accepted and tightened plan Step 4 to discard generated timestamp/count churn. +- 2026-06-18: Focused verification passed: + - `git diff --check` + - `corepack pnpm --dir website run gen-meta` + - `corepack pnpm --dir website exec tsc --noEmit` + - `corepack pnpm --dir website run build` +- 2026-06-18: `gen-meta` and `next build` rewrote `website/lib/generated-meta.json` from `56/129/2010` to current generated counts `61/134/2496` plus timestamp. Per accepted plan review, restored the file because that metadata refresh is unrelated to Issue #494. +- 2026-06-18: Implementation review found the card still named legacy shorthand `/agentmemory/graph` while the registered route is `/agentmemory/graph/query`; accepted and fixed the copy. +- 2026-06-18: Re-verified after reviewer fix: + - `git diff --check` + - `corepack pnpm --dir website exec tsc --noEmit` + - `corepack pnpm --dir website run build` + - `semgrep scan --config p/default --error --metrics=off website/components/Features.tsx docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle` +- 2026-06-18: Passive security review found no new XSS, secret, auth, network, filesystem, dependency, or server-route surface. OSV not run because no dependency, lockfile, container, vendored, package-manager, or third-party package surface changed. +- 2026-06-18: Staged commit gate passed: `gitleaks protect --staged --redact` scanned about 10.23 KB and found no leaks. diff --git a/website/components/Features.tsx b/website/components/Features.tsx index d62458077..93a6c9af3 100644 --- a/website/components/Features.tsx +++ b/website/components/Features.tsx @@ -55,7 +55,7 @@ export function Features({ hooks, mcpTools, restEndpoints }: Props) { unit: "EXTRACTION", title: "KNOWLEDGE GRAPH", text: - "Entities and relations extracted on compress. Query with /agentmemory/graph. Visualize in the viewer. Temporal edges supported.", + "Entities and relations extract after Stop / SessionEnd, with /agentmemory/graph/build for viewer backfills. Query /agentmemory/graph/query for temporal edges.", }, { k: "MESH", From 74dd005cc9bf7d47ff88757f087008cc5654a477 Mon Sep 17 00:00:00 2001 From: Willi Budzinski Date: Thu, 18 Jun 2026 21:41:35 +0200 Subject: [PATCH 2/2] docs: record issue 494 verification --- .../todo.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md index 8b04f6936..5356b0e30 100644 --- a/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md +++ b/docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle/todo.md @@ -49,7 +49,7 @@ Stop conditions: |---|---|---|---| | Validate Issue #494 | Issue view plus local website/README source inspection | In progress | Issue body records upstream PR 727 closed/unmerged with zero files/commits; local `website/components/Features.tsx` still says "Entities and relations extracted on compress." | | Update website copy | Focused diff review and website build/type checks | Complete | `website/components/Features.tsx` now says graph extraction runs after `Stop / SessionEnd`, names `/agentmemory/graph/build` backfill, and uses the real query route `/agentmemory/graph/query`. | -| PR readiness and safety gates | GitHub push prepare workflow, secret/security scans, origin/main base refresh | In progress | `origin/main` refreshed to `a029b7e`; no base merge needed before commit. Targeted Semgrep passed with 0 findings. Staged Gitleaks passed with no leaks. | +| PR readiness and safety gates | GitHub push prepare workflow, secret/security scans, origin/main base refresh | Complete | `origin/main` advanced to `ee72dba7` and was merged without conflicts as `66135b3a`. Post-merge checks passed. Targeted Semgrep passed with 0 findings. Staged and branch-diff Gitleaks passed with no leaks. | | Remote PR lifecycle | Push branch, create PR to `origin/main`, observe CI, merge when green | Pending | Pending after local verification. | ## Subagent Ledger @@ -80,3 +80,11 @@ Stop conditions: - `semgrep scan --config p/default --error --metrics=off website/components/Features.tsx docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle` - 2026-06-18: Passive security review found no new XSS, secret, auth, network, filesystem, dependency, or server-route surface. OSV not run because no dependency, lockfile, container, vendored, package-manager, or third-party package surface changed. - 2026-06-18: Staged commit gate passed: `gitleaks protect --staged --redact` scanned about 10.23 KB and found no leaks. +- 2026-06-18: After commit, `origin/main` advanced from `a029b7e` to `ee72dba7`; merged the exact captured base into this branch without conflicts as merge commit `66135b3a`. +- 2026-06-18: Post-base-merge branch diff against `origin/main` remains limited to this task's plan, todo, and `website/components/Features.tsx`. +- 2026-06-18: Post-base-merge verification passed: + - `git diff --check refs/remotes/origin/main...HEAD` + - `corepack pnpm --dir website exec tsc --noEmit` + - `semgrep scan --config p/default --error --metrics=off website/components/Features.tsx docs/todos/2026-06-18-issue-494-graph-extraction-lifecycle` + - `gitleaks detect --source . --redact --log-opts refs/remotes/origin/main..HEAD` +- 2026-06-18: Extra current-tree `gitleaks detect --source . --redact --no-git` reported 6 findings, all in ignored local Next.js build outputs under `website/.next/` (`.previewinfo`, `.rscinfo`, `prerender-manifest.json`, `server-reference-manifest.json`). These are not tracked and not part of the PR diff; the staged and branch-diff scans are clean.