project-knowledge 0.1.0

package/_site/start.bat

@@ -0,0 +1,26 @@
+@echo off
+setlocal
+
+REM KB Management Site launcher — double-click to start
+set KB_SITE=%~dp0
+set PORT=7777
+
+REM Check if already running
+netstat -ano | findstr ":%PORT% " | findstr "LISTENING" >nul 2>&1
+if %ERRORLEVEL%==0 (
+  echo [kb-site] Already running on port %PORT%. Opening browser...
+  start "" "http://localhost:%PORT%/"
+  goto :eof
+)
+
+echo [kb-site] Starting server on port %PORT%...
+start "KB-Site" /min cmd /c "cd /d "%KB_SITE%" && node server.js"
+timeout /t 2 /nobreak >nul
+
+REM Open browser
+start "" "http://localhost:%PORT%/"
+
+echo.
+echo [kb-site] Server started. To stop: close the "KB-Site" window, or run stop.bat
+echo.
+pause

package/_site/stop.bat

@@ -0,0 +1,11 @@
+@echo off
+setlocal
+set PORT=7777
+
+echo [kb-site] Stopping server on port %PORT%...
+for /f "tokens=5" %%P in ('netstat -ano ^| findstr ":%PORT% " ^| findstr "LISTENING"') do (
+  taskkill /F /PID %%P >nul 2>&1
+  echo [kb-site] Killed PID %%P
+)
+echo Done.
+pause

package/ai-profiles.json

@@ -0,0 +1,18 @@
+{
+  "schema": "ai-profiles/v1",
+  "defaultProfileId": "mock-agent",
+  "profiles": [
+    {
+      "id": "mock-agent",
+      "name": "Mock",
+      "enabled": true,
+      "implementation": "mock-agent"
+    },
+    {
+      "id": "claude-code-agent",
+      "name": "Claude Code",
+      "enabled": false,
+      "implementation": "claude-code-agent"
+    }
+  ]
+}

package/docs/ai-knowledge-base-system-design.md

@@ -0,0 +1,395 @@
+# AI Project Knowledge Base System Design
+
+Status: draft for implementation planning
+Date: 2026-06-11
+Owner: SanQian.Xu
+Project goal source: `docs/project-goal.md`
+
+## 1. Purpose
+
+This project will evolve from a local knowledge-base management site into an AI-assisted project supervision system driven by Git history.
+
+The system must import selected local projects, verify that they are Git repositories, understand project goals, analyze the current implementation, watch new commits, and keep the project's knowledge base accurate enough for a future PR-review project to use as its source of truth.
+
+The central product requirement is:
+
+- A project goal is the highest-priority human-controlled truth.
+- Project analysis is an AI-generated explanation of the current implementation.
+- Git commit analysis must explain code changes, affected features/modules, project-wide impact, and relationship to the project goal.
+- AI output must be testable, reviewable, and evidence-backed before it becomes trusted knowledge.
+
+## 2. Current State
+
+The repository currently contains:
+
+- A local management site under `_site/`.
+- Project registry data in `projects.json`.
+- A PowerShell generator at `scripts/gen-commit-doc.ps1`.
+- Project knowledge folders under `projects/<slug>/`.
+
+The current generator reads Git logs and creates or appends Markdown files mainly from commit subjects. It does not yet deeply inspect diffs, read related source files, run an AI analysis loop, maintain a project goal, or produce draft review workflows.
+
+## 3. Design Principles
+
+1. Project goal first.
+   `project-goal.md` is the authority. AI may propose edits, but must not overwrite the accepted goal automatically.
+
+2. Current implementation is not the same as the goal.
+   `project-analysis.md` describes what the code currently does. It may change often. It is evidence, not intent.
+
+3. Draft before apply.
+   AI-generated changes are written to `_ai/drafts/` first. Formal knowledge files are updated only after an apply step.
+
+4. Evidence required.
+   AI claims must include supporting files, commits, or command outputs. Future PR review must be able to trace a conclusion back to evidence.
+
+5. Machine-readable plus human-readable.
+   Markdown is for people. `kb-manifest.json`, run records, and dependency maps are for automation.
+
+6. Tests define completion.
+   A task is not complete until its test plan passes. Failed tests send the work back to implementation.
+
+## 4. Target Knowledge Base Layout
+
+Each imported project should use this layout:
+
+```text
+projects/<slug>/
+├─ README.md
+├─ project-goal.md
+├─ project-analysis.md
+├─ kb-manifest.json
+├─ architecture/
+│  ├─ overview.md
+│  ├─ data-flow.md
+│  └─ decisions/
+├─ requirements/
+│  ├─ roadmap.md
+│  ├─ constraints.md
+│  └─ success-criteria.md
+├─ features/
+│  ├─ 00-index.md
+│  └─ <feature-slug>.md
+├─ modules/
+│  ├─ 00-index.md
+│  └─ <module-slug>.md
+├─ changes/
+│  ├─ 00-index.md
+│  └─ <commit-hash>.md
+├─ quality/
+│  ├─ review-rules.md
+│  ├─ test-strategy.md
+│  └─ risk-register.md
+├─ references/
+│  ├─ source-map.md
+│  └─ dependency-map.json
+└─ _ai/
+   ├─ drafts/
+   ├─ runs/
+   └─ context-packs/
+```
+
+### 4.1 `project-goal.md`
+
+This file captures the true goal of the project. It is the future PR-review project's highest-priority input.
+
+Required sections:
+
+- One-sentence goal
+- Target users
+- Core scenarios
+- Success criteria
+- Non-goals
+- Priority principles
+- PR review principles
+- Human revision history
+
+Suggested frontmatter:
+
+```yaml
+schema: project-goal/v1
+project: <slug>
+status: accepted
+source: human-reviewed
+updatedAt: <YYYY-MM-DD>
+lastReviewedBy: SanQian.Xu
+```
+
+### 4.2 `project-analysis.md`
+
+This file describes the current implementation and how it serves the project goal.
+
+Required sections:
+
+- AI-inferred project purpose
+- Current implemented capabilities
+- Current architecture
+- Important modules
+- Data/control flow
+- How current implementation supports the project goal
+- Gaps between implementation and project goal
+- Evidence list
+
+This file may be regenerated after full-project analysis.
+
+### 4.3 `features/`
+
+Feature documents are long-lived knowledge. They should not be one file per commit. A feature document may be created by the first relevant change and then updated by later commits.
+
+Each feature document must explain:
+
+- What the feature does
+- Why it exists
+- Which project-goal scenario it supports
+- Main user/system behavior
+- Source files and modules involved
+- Important commits
+- Known limitations
+- Tests or verification points
+
+### 4.4 `changes/`
+
+Change documents are commit- or batch-level records. They answer:
+
+- What changed?
+- Which files changed?
+- Which feature/module did the change affect?
+- Is this a new feature, existing feature update, bug fix, refactor, or infrastructure change?
+- What is the impact on the project goal?
+- What evidence supports the analysis?
+
+The existing `commits/` directory can remain for compatibility during migration, but new AI-driven change records should target `changes/`.
+
+### 4.5 `kb-manifest.json`
+
+This file is the machine-readable contract for future tools.
+
+Example shape:
+
+```json
+{
+  "schema": "kb-manifest/v1",
+  "project": "example-project",
+  "goal": {
+    "path": "project-goal.md",
+    "status": "accepted",
+    "updatedAt": "2026-06-11"
+  },
+  "analysis": {
+    "path": "project-analysis.md",
+    "lastAnalyzedCommit": "abc1234",
+    "updatedAt": "2026-06-11"
+  },
+  "indexes": {
+    "features": "features/00-index.md",
+    "modules": "modules/00-index.md",
+    "changes": "changes/00-index.md",
+    "sourceMap": "references/source-map.md"
+  },
+  "trustedKnowledge": [
+    "project-goal.md",
+    "features/",
+    "modules/",
+    "architecture/"
+  ]
+}
+```
+
+## 5. Project Registry Model
+
+`projects.json` should be extended gradually. Target fields:
+
+```json
+{
+  "displayName": "Example Project",
+  "localPath": "D:\\SanQian.Xu\\Example",
+  "gitPath": "D:\\SanQian.Xu\\Example",
+  "kbPath": "D:\\SanQian.Xu\\project-knowledge-base\\projects\\example",
+  "enabled": true,
+  "repoStatus": "ok",
+  "defaultBranch": "main",
+  "currentBranch": "main",
+  "remoteUrl": "https://...",
+  "headCommit": "abc1234",
+  "lastSeenCommit": "abc1234",
+  "lastAnalyzedCommit": "def5678",
+  "aiProfileId": "default-agent",
+  "kbSchemaVersion": "v2",
+  "goalStatus": "accepted"
+}
+```
+
+The import flow must validate:
+
+- `localPath` exists.
+- `gitPath` exists.
+- `git -C <gitPath> rev-parse --is-inside-work-tree` succeeds.
+- `git -C <gitPath> rev-parse HEAD` succeeds, or the UI clearly reports that the repository has no commits.
+- The knowledge base directory is initialized with the v2 layout.
+
+## 6. Runtime Architecture
+
+```mermaid
+flowchart LR
+    UI["Local Web UI"] --> API["Node Local API"]
+    API --> Registry["Project Registry"]
+    API --> Git["Git Inspector"]
+    API --> Orchestrator["Analysis Orchestrator"]
+    Orchestrator --> Context["Context Pack Builder"]
+    Orchestrator --> Agent["AI Agent Adapter"]
+    Agent --> Drafts["Draft Writer"]
+    Drafts --> Review["Review / Apply"]
+    Review --> KB["Knowledge Base Files"]
+    KB --> Manifest["kb-manifest.json"]
+```
+
+### 6.1 Local API
+
+The current `_site/server.js` can stay as the local API host initially. As complexity grows, extract route handlers into modules.
+
+New endpoint candidates:
+
+- `POST /api/projects/:slug/validate-git`
+- `POST /api/projects/:slug/analyze/initial`
+- `POST /api/projects/:slug/analyze/commits`
+- `GET /api/projects/:slug/goal`
+- `PUT /api/projects/:slug/goal`
+- `GET /api/projects/:slug/drafts`
+- `POST /api/projects/:slug/drafts/:draftId/apply`
+- `GET /api/projects/:slug/manifest`
+- `GET /api/ai-profiles`
+- `PUT /api/ai-profiles`
+
+### 6.2 Analysis Orchestrator
+
+The orchestrator coordinates:
+
+1. Identify the project and Git range.
+2. Build context packs.
+3. Start the selected AI adapter.
+4. Validate model output against schema.
+5. Write draft documents.
+6. Record run metadata.
+7. Update project analysis state only after successful apply.
+
+### 6.3 Context Pack Builder
+
+The system should automatically collect context. The user should not manually choose files.
+
+Inputs:
+
+- Git diff and stats
+- Changed files
+- Neighboring source files when needed
+- Existing `project-goal.md`
+- Existing feature/module/source-map docs
+- Package/config files
+- Test files near changed code
+
+The context pack must record why each file was included.
+
+### 6.4 AI Agent Adapter
+
+The default strategy should be agent-first for deep analysis:
+
+- Use a Claude Code / agent-style analyzer for repository-wide reading, command execution, and cross-file reasoning.
+- Use ordinary cloud model APIs for smaller structured tasks only when the context pack is already sufficient.
+- Keep the adapter interface provider-neutral so different analyzers can be swapped later.
+
+The adapter must return structured output that includes:
+
+- Summary
+- Classification
+- Affected goals/features/modules
+- Project-goal impact
+- Evidence
+- Proposed file operations
+- Confidence
+- Questions or human-review flags
+
+### 6.5 Draft Writer and Apply Step
+
+AI output should first become draft files under:
+
+```text
+projects/<slug>/_ai/drafts/<run-id>/
+```
+
+Apply is a separate step that:
+
+- Validates draft schema.
+- Shows file changes.
+- Creates backups or patch records.
+- Writes formal knowledge files.
+- Updates `kb-manifest.json`.
+- Updates `lastAnalyzedCommit` only after all required writes pass.
+
+## 7. Main Workflows
+
+### 7.1 Import Project
+
+```mermaid
+flowchart TD
+    A["User enters path"] --> B["Validate path"]
+    B --> C["Validate Git repository"]
+    C --> D["Create or update projects.json"]
+    D --> E["Initialize KB v2 layout"]
+    E --> F["Show repository status in UI"]
+```
+
+### 7.2 Initial Project Analysis
+
+```mermaid
+flowchart TD
+    A["Start initial analysis"] --> B["Read repository structure"]
+    B --> C["Read README/config/package files"]
+    C --> D["Infer project goal draft"]
+    D --> E["Generate project-analysis draft"]
+    E --> F["Generate modules/features/source map drafts"]
+    F --> G["User reviews project-goal.md"]
+    G --> H["Apply accepted knowledge"]
+```
+
+### 7.3 Incremental Commit Analysis
+
+```mermaid
+flowchart TD
+    A["Detect new commits"] --> B["Build commit diff context"]
+    B --> C["Read existing KB"]
+    C --> D["AI classifies change"]
+    D --> E{"New or existing feature?"}
+    E -->|New| F["Draft new feature doc"]
+    E -->|Existing| G["Draft feature/module update"]
+    D --> H["Draft change record"]
+    F --> I["Review/apply"]
+    G --> I
+    H --> I
+```
+
+## 8. Quality Gates
+
+A task is not done unless:
+
+- Required automated tests pass.
+- Generated knowledge has evidence links.
+- AI drafts are not applied directly without validation.
+- `project-goal.md` is never overwritten automatically.
+- `lastAnalyzedCommit` is updated only after successful knowledge write.
+- Failures are visible in the UI or run records.
+
+## 9. Migration Strategy
+
+Phase 1 should not delete existing `commits/` files. Instead:
+
+1. Add v2 layout to new or reinitialized projects.
+2. Keep old `commits/` readable.
+3. Write new AI-driven change records to `changes/`.
+4. Add `kb-manifest.json`.
+5. Add migration tests before changing existing project data in bulk.
+
+## 10. Open Decisions
+
+1. Which agent runtime will be used first: Claude Code CLI, Claude Agent SDK, or a local command wrapper?
+2. Should AI-generated project goal drafts require explicit user approval before any later analysis uses them as authoritative?
+3. How large can a context pack be before the analyzer must split work into multiple passes?
+4. Should the future PR-review project read only `kb-manifest.json` and accepted docs, or also read AI run history?

package/docs/pr-consumer-contract.md

@@ -0,0 +1,198 @@
+# PR Consumer Contract (TASK-011)
+
+Status: stable
+Date: 2026-06-11
+
+This document is the contract that the future PR-review project (and any other
+external tool) can rely on when reading the knowledge base. It is intentionally
+narrow: if you can satisfy these rules, you can build a consumer without
+negotiating with the KB site maintainers.
+
+## 1. Where the KB lives
+
+For a project with slug `foo`:
+
+```
+project-knowledge-base/
+└ projects/
+  └ foo/                                       ← kbPath (also in projects.json)
+    ├ README.md                                ← required, seed entry
+    ├ framework.md                             ← optional, seed entry
+    ├ project-goal.md                          ← THE goal (only if accepted)
+    ├ project-analysis.md                      ← only if accepted
+    ├ kb-manifest.json                         ← THE contract
+    ├ architecture/                            ← trusted dir (TASK-003 seed)
+    ├ modules/                                 ← trusted dir
+    ├ features/                                ← trusted dir; one file per feature
+    ├ changes/                                 ← trusted dir; one file per change
+    ├ quality/                                 ← trusted dir
+    ├ requirements/                            ← trusted dir
+    ├ references/                              ← trusted dir
+    └ _ai/                                     ← NEVER trusted
+      ├ drafts/<runId>/...                     ← AI-generated drafts
+      ├ runs/<runId>.json                      ← AI run records
+      ├ backups/<runId>/...                    ← backups taken at apply time
+      └ context-packs/<runId>/context-pack.json
+```
+
+The registry entry in `projects.json` carries `kbPath` (the absolute path
+to the project folder). The KB root is `path.dirname(kbPath)`; the registry
+file is at `<KB_ROOT>/projects.json`.
+
+## 2. The manifest
+
+`kb-manifest.json` is the only file external tools MUST parse. Its schema is
+`kb-manifest/v1`. The current shape:
+
+```json
+{
+  "schema": "kb-manifest/v1",
+  "project": "foo",
+  "kbRoot": "projects/foo",
+  "generatedAt": "2026-06-11",
+  "goal": { "path": "project-goal.md", "status": "accepted", "updatedAt": "2026-06-11" },
+  "analysis": {
+    "path": "project-analysis.md",
+    "lastAnalyzedCommit": "abc1234…",
+    "updatedAt": "2026-06-11"
+  },
+  "indexes": {
+    "features":  "features/00-index.md",
+    "modules":   "modules/00-index.md",
+    "changes":   "changes/00-index.md",
+    "sourceMap": "references/source-map.md"
+  },
+  "trustedKnowledge": [
+    "README.md", "framework.md",
+    "architecture/", "modules/", "features/", "changes/", "quality/",
+    "requirements/", "references/"
+  ],
+  "draftAreas": [
+    "_ai/drafts/", "_ai/runs/", "_ai/context-packs/", "_ai/backups/"
+  ]
+}
+```
+
+### 2.1 Required fields for consumers
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `schema` | string | MUST be `kb-manifest/v1` |
+| `project` | string | matches the slug in `projects.json` |
+| `goal.path` | string\|null | relative to `kbPath`. `null` (or absent) means "no accepted goal yet" — the consumer must NOT invent one. |
+| `goal.status` | string | `accepted` \| `not-created` \| `pending`. Consumers should treat anything other than `accepted` as "no goal". |
+| `analysis.path` | string\|null | relative to `kbPath`. `null` means "no accepted analysis yet". |
+| `analysis.lastAnalyzedCommit` | string\|null | the commit that produced the current accepted analysis. `null` if the project was never analyzed. |
+| `trustedKnowledge` | string[] | relative paths. Each is either a file or a directory ending in `/`. The consumer may treat these as authoritative. |
+| `draftAreas` | string[] | relative paths. The consumer MUST NOT read from these as authoritative content. |
+
+### 2.2 Knowledge priority order
+
+When assembling a review context, read in this order so the human-aligned
+"goal" is always the loudest voice:
+
+1. `project-goal.md` (if `goal.status === 'accepted'`)
+2. accepted feature docs under `features/`
+3. accepted module docs under `modules/`
+4. accepted architecture under `architecture/`
+5. accepted analysis under `project-analysis.md`
+6. accepted change history under `changes/`
+7. run history under `_ai/runs/` (audit only; never treated as authoritative)
+
+Drafts under `_ai/drafts/` are NEVER part of the trusted story. They are a
+queue waiting for human review at the Drafts tab.
+
+## 3. The apply gate
+
+Nothing under `_ai/` becomes trusted by accident. The only way for a draft
+to leave `_ai/drafts/` and land in the formal KB is the `applyDrafts` flow
+in `_site/lib/draft-apply.js`, which:
+
+1. Refuses to overwrite `project-goal.md` without `allowGoalEdit: true`.
+2. Refuses to write anywhere under `_ai/`.
+3. Backs up any file it overwrites into `_ai/backups/<runId>/`.
+4. Updates the manifest in place.
+5. Marks the run record as `applyStatus: 'applied'`.
+
+A consumer that wants to verify a path is "really trusted" should call
+`POST /api/projects/<slug>/validate-kb` (server-side validation) or
+run `_site/lib/kb-validator.js` directly.
+
+## 4. PR context pack
+
+`GET /api/projects/<slug>/pr-context` returns a JSON pack conforming to
+`pr-context-pack/v1`:
+
+```json
+{
+  "schema": "pr-context-pack/v1",
+  "generatedAt": "2026-06-11T...",
+  "project": "foo",
+  "goal": { "path": "project-goal.md", "content": "…", "size": 1234 },
+  "analysis": { "path": "project-analysis.md", "content": "…", "size": 5678 },
+  "indexes": {
+    "features":  { "path": "features/00-index.md", "content": "…", "size": 200 },
+    "modules":   { "path": "modules/00-index.md",  "content": "…", "size": 200 },
+    "changes":   { "path": "changes/00-index.md",  "content": "…", "size": 200 },
+    "sourceMap": { "path": "references/source-map.md", "content": "…", "size": 100 }
+  },
+  "trustedKnowledge": [
+    { "path": "README.md", "content": "…", "size": 80 },
+    { "path": "framework.md", "content": "…", "size": 200 }
+  ]
+}
+```
+
+The pack never includes anything under `_ai/`. The consumer can serialize
+this directly into its own context window.
+
+## 5. Validation
+
+A consumer can rely on the validator at `_site/lib/kb-validator.js`. It
+exposes `validateKb(kbPath)` and `buildPrContextPack(kbPath)`. The server
+exposes the same logic at `POST /api/projects/<slug>/validate-kb` and
+`GET /api/projects/<slug>/pr-context`.
+
+`validateKb` returns:
+
+```json
+{
+  "ok": true,
+  "status": 200,
+  "info": {
+    "kbPath": "...",
+    "manifestExists": true,
+    "goalStatus": "accepted",
+    "analysisStatus": "present",
+    "trustedKnowledgeEntries": 9,
+    "draftAreasEntries": 4,
+    "aiSubdirsPresent": ["_ai/drafts/", "_ai/runs/", "_ai/context-packs/"]
+  },
+  "warnings": [],
+  "errors": []
+}
+```
+
+When `ok: false`, `errors` is a list of human-readable strings.
+
+## 6. Versioning
+
+The `schema` field on both the manifest and the PR context pack is the
+contract version. The server is currently on `v1` for both. If a breaking
+change is needed, the server will move to `v2` and keep `v1` endpoints
+working for at least one major release.
+
+## 7. Test fixtures
+
+The PR consumer project can drop these fixtures into its own test suite:
+
+- `_site/_test/fixtures/pr-context/healthy/` — a healthy v2 KB, should
+  validate clean and produce a PR context pack.
+- `_site/_test/fixtures/pr-context/missing-goal/` — accepted analysis,
+  no goal. Should validate (the validator reports `goalStatus: 'not-created'`)
+  and the PR context pack's `goal` field is `null`.
+- `_site/_test/fixtures/pr-context/draft-leak/` — manifest trusts a path
+  inside `_ai/`. The validator MUST refuse.
+
+These fixtures are byte-for-byte reproducible: every file is checked in
+and the test that consumes them just reads from disk.