@justestif/pk 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@justestif/pk",
+  "version": "0.1.0",
+  "description": "Project knowledge — structured intake, search, and recall",
+  "bin": {
+    "pk": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skill/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun && printf '#!/usr/bin/env bun\n' | cat - dist/index.js > dist/tmp.js && mv dist/tmp.js dist/index.js && chmod +x dist/index.js",
+    "check": "bun run typecheck && bun run lint && bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx eslint src/",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "markdownlint": "^0.40.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justEstif/pk.git"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest",
+    "eslint": "^9.0.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pk
+description: "Load when maintaining project knowledge, capturing decisions or questions, looking up what the project knows, organizing notes, running knowledge intake, or initializing a project knowledge base. Keywords: pk, project knowledge, decision log, note, source, question log, knowledge base, intake."
+---
+
+# pk
+
+Structured project knowledge — intake, search, recall, and audit over `knowledge/`.
+
+## Prerequisites
+
+Verify before every operation:
+
+```bash
+pk --version 2>/dev/null || npm install -g @justestif/pk
+```
+
+## First use in a project
+
+```bash
+pk init
+```
+
+Creates `knowledge/`, installs Claude Code hook at `.claude/hooks/pk-user-prompt-submit.ts`.
+The hook injects open questions, recent decisions, and active notes into every prompt automatically.
+
+## Commands
+
+```bash
+pk new <type> <title> [--tags tag1,tag2]   # type: note|decision|question|source
+pk search <query> [--context] [--limit 5]
+pk synthesize [query] [--all] [--session-start]
+pk index                                    # rebuild FTS5 + markdown indexes
+pk lint                                     # validate structure — exit 1 on errors
+pk instructions <command>                   # full behavioral guide per command
+```
+
+Run all commands from the project root (where `knowledge/` lives).
+
+## Intake
+
+**Search before creating** — always run `pk search` first.
+
+- Substantial messy input → `source`. Extract `note`, `decision`, `question` only when durable beyond this session.
+- Update existing when the match is obvious; otherwise create and link in body.
+- Run `pk lint` before committing. Auto-commit coherent operations only when lint passes and no unrelated files are staged.
+
+## Asking
+
+1. `pk search <query> [--context]`
+2. Read top results directly
+3. Answer with citations to note paths/IDs
+4. If silent or ambiguous, offer to create a `question` note
+
+## NEVER
+
+- **Skip `pk search` before creating** — duplicates erode trust in the knowledge base
+- **Dump raw input into durable notes** — preserve in `source`, extract selectively
+- **Silently merge related-but-different claims** — create and link instead
+- **Auto-commit when lint fails or unrelated files are staged**
+
+## References
+
+Load only when the task requires it:
+
+- `references/knowledge-model.md` — types, folders, frontmatter schema, required sections
+- `references/git-workflow.md` — commit policy, safety stops
+- `references/source-principles.md` — documentation governance

package/skill/assets/templates/decision.md

@@ -0,0 +1,29 @@
+---
+id: decision-{{date}}-{{slug}}
+type: decision
+title: {{title}}
+created: {{date}}
+updated: {{date}}
+status: accepted
+tags: [{{tags}}]
+---
+
+## Decision
+
+What was decided.
+
+## Context
+
+Why this decision came up.
+
+## Rationale
+
+Why this option won.
+
+## Consequences
+
+What this changes or constrains.
+
+## Related
+
+Links to source, questions, notes, or superseded decisions.

package/skill/assets/templates/index.md

@@ -0,0 +1,25 @@
+---
+id: index-{{slug}}
+type: index
+title: {{title}}
+created: {{date}}
+updated: {{date}}
+status: active
+tags: [{{tags}}]
+---
+
+## Purpose
+
+What this index helps navigate.
+
+## Key Links
+
+Curated links.
+
+## Open Questions
+
+Relevant unresolved questions.
+
+## Recent Changes
+
+Notable updates.

package/skill/assets/templates/note.md

@@ -0,0 +1,25 @@
+---
+id: note-{{date}}-{{slug}}
+type: note
+title: {{title}}
+created: {{date}}
+updated: {{date}}
+status: active
+tags: [{{tags}}]
+---
+
+## Summary
+
+One short paragraph.
+
+## Details
+
+Durable project knowledge.
+
+## Evidence
+
+Source links, files, quotes, or observations.
+
+## Related
+
+Links to related notes, decisions, or questions.

package/skill/assets/templates/question.md

@@ -0,0 +1,25 @@
+---
+id: question-{{date}}-{{slug}}
+type: question
+title: {{title}}
+created: {{date}}
+updated: {{date}}
+status: open
+tags: [{{tags}}]
+---
+
+## Question
+
+The unresolved question.
+
+## Why It Matters
+
+What decision or work this blocks or informs.
+
+## Current Understanding
+
+Known facts and candidate answers.
+
+## Resolution
+
+Answer once resolved.

package/skill/assets/templates/source.md

@@ -0,0 +1,21 @@
+---
+id: source-{{date}}-{{slug}}
+type: source
+title: {{title}}
+created: {{date}}
+updated: {{date}}
+status: unprocessed
+tags: [{{tags}}]
+---
+
+## Source
+
+Where this came from.
+
+## Raw Material
+
+Original or lightly cleaned content.
+
+## Extracted Items
+
+Links to notes, decisions, or questions created from this source.

package/skill/references/git-workflow.md

@@ -0,0 +1,77 @@
+# Git Workflow for Project Knowledge
+
+Git is the audit, safety, and review layer for `knowledge/`.
+
+## Before Modifying Knowledge
+
+Check repository state:
+
+```bash
+git status --short
+```
+
+Stop before editing if unrelated user changes would be mixed into the same commit. If changes are clearly knowledge-system work in scope, continue.
+
+## After Modifying Knowledge
+
+Run mechanical maintenance:
+
+```bash
+scripts/knowledge-index
+scripts/knowledge-lint
+```
+
+Review what changed:
+
+```bash
+git diff -- knowledge scripts/knowledge-* assets/templates hk.pkl
+```
+
+Summarize:
+
+- files created
+- files updated
+- generated indexes
+- lint result
+- any ignored/deferred material
+
+## Auto-Commit Policy
+
+Auto-commit coherent completed knowledge operations unless a safety stop applies.
+
+Normal intake commits stage only:
+
+```bash
+git add knowledge/
+```
+
+Knowledge-system implementation commits may stage:
+
+```bash
+git add knowledge/ scripts/knowledge-* assets/templates/ hk.pkl
+```
+
+Use concise commit messages:
+
+```txt
+knowledge: intake <topic>
+knowledge: update <topic>
+knowledge: answer <topic>
+knowledge-system: update <topic>
+```
+
+## Safety Stops
+
+Do not auto-commit when:
+
+- unrelated project files are modified
+- lint fails
+- the edit deletes or rewrites existing knowledge ambiguously
+- the working tree contains user changes outside the allowed commit boundary
+- the user says not to commit
+
+When stopped, report the exact reason and show the staged/unstaged state.
+
+## Hooks
+
+If hk is used, run `knowledge-lint` on pre-commit only when `knowledge/**/*.md` changes. Avoid every-N-commit scheduling; it is arbitrary and less transparent than change-triggered checks.

package/skill/references/knowledge-model.md

@@ -0,0 +1,127 @@
+# Project Knowledge Model
+
+## Scope
+
+This system is project-specific. It is not a personal second brain, a full wiki platform, or a semantic memory database.
+
+The canonical store is plain markdown under `knowledge/`. Beans/issues remain for trackable work; the knowledge base is for durable context and future answers.
+
+## Folder and Type Rules
+
+| Type | Folder | Purpose | Status values |
+| --- | --- | --- | --- |
+| `source` | `knowledge/sources/` | Provenance and raw/lightly cleaned input | `unprocessed`, `processed`, `archived` |
+| `note` | `knowledge/notes/` | Durable project knowledge | `active`, `superseded`, `archived` |
+| `decision` | `knowledge/decisions/` | Chosen direction and rationale | `proposed`, `accepted`, `superseded` |
+| `question` | `knowledge/questions/` | Unresolved or resolved uncertainty | `open`, `answered`, `obsolete` |
+| `index` | `knowledge/indexes/` | Navigation/MOC pages | `active`, `archived` |
+
+## Frontmatter
+
+Required fields only:
+
+```yaml
+---
+id: note-YYYY-MM-DD-short-slug
+type: note
+title: Short title
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+status: active
+tags: [tag-one, tag-two]
+---
+```
+
+Rules:
+
+- `id` must be unique across `knowledge/**/*.md`.
+- `type` must match both status set and folder.
+- `tags` must be a flat list of lowercase slugs.
+- Do not use nested YAML, multiline YAML, or relationship arrays.
+
+## Required Sections
+
+### source
+
+- `## Source`
+- `## Raw Material`
+- `## Extracted Items`
+
+### note
+
+- `## Summary`
+- `## Details`
+- `## Evidence`
+- `## Related`
+
+### decision
+
+- `## Decision`
+- `## Context`
+- `## Rationale`
+- `## Consequences`
+- `## Related`
+
+### question
+
+- `## Question`
+- `## Why It Matters`
+- `## Current Understanding`
+- `## Resolution`
+
+### index
+
+- `## Purpose`
+- `## Key Links`
+- `## Open Questions`
+- `## Recent Changes`
+
+## Intake Triage
+
+Classify extracted material this way:
+
+- Raw/provenance-heavy material → `source`
+- Stable project fact/explanation/constraint → `note`
+- Chosen path with rationale/consequences → `decision`
+- Unknown that blocks or informs work → `question`
+- Navigation over a topic/type/tag → `index`
+- Action item/task → issue tracker, not a knowledge note
+- Low-signal commentary → ignore or keep only in `source`
+
+## Update Policy
+
+Search before creating durable notes.
+
+- Exact or obvious same claim/topic → update existing note, preserving provenance.
+- Related but not same → create a new note and link both in body sections.
+- Contradictory or superseding claim → do not overwrite silently; explain the conflict and use status/linking.
+- Unsure → create or update a `question` note.
+
+## Lint Policy
+
+Hard failures:
+
+- missing frontmatter
+- missing required fields
+- duplicate `id`
+- invalid `type`
+- invalid `status` for type
+- file in wrong folder for `type`
+- required sections missing
+- broken internal markdown/wiki links
+
+Warnings:
+
+- empty `tags`
+- length threshold exceeded
+- `source` marked `processed` with no extracted items
+
+Length warning thresholds:
+
+- `question`: 80 lines
+- `decision`: 120 lines
+- `note`: 150 lines
+- `index`: 200 lines
+- `source`: 400 lines
+
+Hard fail non-source notes over 400 lines.

package/skill/references/source-principles.md

@@ -0,0 +1,73 @@
+# Governance Documentation Source Principles
+
+Based on Frederick Vanbrabant's articles:
+
+- Governance: Documentation as a Knowledge Network (2026-03-07)
+- Governance: Documentation to support projects (2026-03-22)
+
+## Knowledge Network Principles
+
+- Tools are usually not the problem; setup is. Confluence, Notion, Slite, SharePoint, etc. can work if the information architecture is deliberate.
+- Knowledge graph beats folder dump: valuable knowledge is often in relationships between pages, not only in page content.
+- MOCs (Maps of Content) are landing pages that both introduce a topic and route readers to deeper nodes.
+- Atomic documentation means one concept per page. Use links/transclusion instead of repeating definitions.
+- Folder structure remains useful as an adoption ramp for new users, but links should become the primary navigation once readers enter.
+- Recommended top-level folders: Projects, Applications, Processes, Resources, Archive.
+- Archive prevents broken links and preserves reuse value; use banners/status where tooling allows.
+- Metadata worth adding: creation date, last-updated date, author, maybe status. Old information is not automatically bad.
+- LLMs should support writing, not replace ownership. Atomic, linked notes reduce temptation to generate giant documents.
+
+## Project Documentation Principles
+
+Documentation should grow organically from actual project communication and problems. If an issue happened once, documenting it prevents repeated confusion.
+
+Four project areas:
+
+1. **Strategy** — Business Case, Kick-off Document.
+2. **Logs** — Open Questions Log, Decision Log, Constraint Log, Meeting Notes.
+3. **Blueprints** — TO-BE Diagram, AS-IS Diagram, Data Model, Phasing Diagrams.
+4. **Program Management** — Gantt chart / critical path.
+
+### Core Project Artifacts
+
+Always consider these first:
+
+- Business Case: the approved why; missing clarity causes drift.
+- Decision & Question Logs: high-value historical nodes for future maintainers.
+- TO-BE Diagram: quick shared reference for what changes.
+- Gantt: centralizes timing, gates, dependencies, and impact.
+
+### Logs
+
+Question Log fields: ID, descriptive name, dated history, priority, assignee, status. Link solved questions to the Decision Log.
+
+Decision Log should capture: decision, context/question, chosen option, alternatives considered, why alternatives were rejected, constraints/trade-offs.
+
+Constraint Log should capture budget, compliance, technical constraints, and other non-negotiables useful for onboarding.
+
+Meeting notes can be AI-assisted because they are raw project evidence, not polished canonical docs.
+
+### Diagrams
+
+Keep both editable raw formats and static exports. Add labels: author, date, status. For large projects, include AS-IS, TO-BE, and phase views. Data models help tool experts reason in systems of record and data flows.
+
+### Project Close
+
+At close, project docs should not fade out. Run a retrospective and merge durable artifacts:
+
+- Project target state becomes current state for the relevant application/process.
+- Decisions/questions/constraints move or link into affected domain nodes.
+- Diagrams move to application/process/resource areas.
+- Remaining project material moves to Archive.
+
+## Evaluation Heuristics
+
+Ask these when reviewing a documentation system:
+
+- Can a newcomer find the right starting MOC in two clicks?
+- Does each important concept have one canonical definition?
+- Are decisions linked from the applications/processes they affect?
+- Are open questions visible enough to manage project risk?
+- Can readers move from high-level overview to technical specifics by following links?
+- Would deleting a project folder break useful organisational memory?
+- Is documentation scaled to risk, or copied from a framework checklist?