whykit 0.3.1__py3-none-any.whl

whykit/template/INTEROP.md

@@ -0,0 +1,117 @@
+---
+title: Working across repositories
+aliases:
+  - INTEROP
+type: guide
+status: approved
+owner: WhyKit maintainers
+created: 2026-09-17
+last_updated: 2026-09-17
+source_of_truth: true
+sensitivity: public
+tags:
+  - governance
+  - interop
+---
+
+# Working across repositories
+
+This repository holds reasoning. The company's other repositories hold systems.
+They are edited in the same sessions, by the same people and agents, and that is
+exactly where things go wrong. These are the rules that keep them apart.
+
+## The split
+
+| | Knowledge repository | Code repository |
+|---|---|---|
+| Source of truth for | Why a thing was decided, what we believe, what we measured | What the system actually does |
+| Changes when | A decision, a finding or a definition changes | Behaviour changes |
+| Read by | People, agents, new joiners | Build pipelines, runtimes |
+| Safe to be wrong in | No — it is quoted later as fact | It fails loudly |
+
+The rule that follows: **never describe current system behaviour here as fact.**
+Describe the decision and link to the code. Code drifts; a decision does not. A
+sentence here saying "the form sends X" will be false within a quarter and nobody
+will notice. A sentence saying "D-041: we decided the form should send X, see
+`web/src/forms/Contact.tsx`" stays true even after the code changes, because it
+records a decision, and the link shows what happened to it.
+
+## Checkout layout
+
+Assume every repository is a sibling directory under one workspace root:
+
+```
+workspace/
+  knowledge/        <- this repository
+  web/
+  api/
+  infra/
+```
+
+Nothing enforces this, but the link convention below reads naturally only if it
+holds. If your layout differs, write it down here, because every agent that opens
+this file will otherwise assume the layout above.
+
+## Linking to another repository
+
+Always prefix the repository name, and always use the path from that
+repository's root:
+
+```
+web/src/components/BookingEmbed.astro
+api/server.py:112
+```
+
+Never write a path from inside a subdirectory, and never write an absolute path
+from someone's machine. A bare `src/components/BookingEmbed.astro` is ambiguous
+the moment a second repository has a `src/components/`, and an absolute path is
+wrong for everyone except its author.
+
+Link to a line number only when pointing at a specific decision point. Line
+numbers rot faster than paths, so prefer naming the function or the section.
+
+## What lives where when a change touches both
+
+A change that spans repositories produces two artefacts, not one:
+
+1. **A decision record here**, in `06-decisions/`, carrying the reasoning, the
+   alternatives, the evidence and the consequences.
+2. **The change itself in the code repository**, whose commit message references
+   the decision ID.
+
+Neither is a summary of the other. The decision record explains a choice to a
+person who was not there; the commit explains a change to someone reading a diff.
+
+When a decision is reversed, append a new record and mark the old one
+`superseded`. Do not edit the original into agreement with the present.
+
+## Rules for agents crossing a repository boundary
+
+1. **Do not clone, pull or fetch other repositories** because a task mentions
+   them. Work against what is already checked out, and say so if it is missing.
+2. **Do not run a code repository's build, deploy or release commands** from a
+   session anchored here. Knowledge work does not need them, and a deploy
+   triggered as a side effect of research is the worst kind of surprise.
+3. **Do not commit in a repository you were not asked to change.** Cross-repo
+   work produces changes in several working trees; leave them there and report
+   what is uncommitted where.
+4. **Read before claiming.** If a document here asserts something about a code
+   repository, open the file and check before repeating it. The assertion may
+   predate the code.
+5. **Report per repository.** When work touched three repositories, say what
+   changed in each, separately. A merged summary hides which tree is dirty.
+
+## Secrets
+
+No repository in this set holds credentials. This one additionally must not hold
+their *values* in prose, screenshots or pasted logs — a knowledge repository is
+copied, exported and shared far more casually than a code repository.
+
+Record where a secret lives and who can grant it. Never what it is.
+
+## Keeping this file honest
+
+`INTEROP.md` is the one document here that is allowed to describe other
+repositories, and therefore the one most likely to go stale. Review it whenever
+a repository is added, renamed or retired, and put that review on the same
+cadence as the decision-log review.

whykit/template/OBSIDIAN.md

@@ -0,0 +1,92 @@
+---
+title: Obsidian conventions
+aliases:
+  - Vault conventions
+type: guide
+status: approved
+owner: WhyKit maintainers
+created: 2026-09-17
+last_updated: 2026-09-17
+source_of_truth: true
+sensitivity: public
+tags:
+  - governance
+  - obsidian
+---
+
+# Obsidian conventions
+
+Open the repository root as the vault root.
+
+## Compatibility
+
+- UTF-8 Markdown files.
+- No community plugin required for core navigation or reading.
+- Readable in both Obsidian and a plain Git host.
+- YAML front matter for document properties.
+- Obsidian callouts instead of platform-specific block markup.
+
+## Required properties for new working notes
+
+```yaml
+title: Human-readable title
+aliases: []
+type: strategy | research | framework | specification | decision | map-of-content | guide
+status: draft | in_review | approved | superseded | archived
+owner: Owner name
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: internal
+source_ids: []
+tags: []
+```
+
+Templates use `status: template`. `sensitivity` is one of `public`, `internal`, `confidential`, or `restricted`.
+
+`source_of_truth: true` is a claim, not a formality. It means: if another
+document disagrees with this one, this one wins. Very few documents should carry
+it, and every one that does needs an owner who notices when it goes stale.
+
+## Links
+
+- Wikilinks for internal notes: `[[path/to/note|Readable label]]`.
+- Markdown links for external sources.
+- Link to the canonical note instead of duplicating it.
+- Prefer unique note names; add a path where a title could be ambiguous.
+- For files in another repository, follow `INTEROP.md` — those are not wikilinks.
+
+## File names and structure
+
+- Lowercase `kebab-case.md` for normal notes.
+- Root navigation notes may use a readable name, such as `Home.md`.
+- Attachments in `assets/`, linked relatively.
+- No empty heading-only exports, no duplicate stubs.
+- No exporter-generated identifiers in normalized file names.
+- Date-stamped documents end with the date: `name-YYYY-MM-DD.md`. Anything
+  reporting a point in time needs this; a report called `audit.md` is unusable
+  the second time someone runs an audit.
+
+## Obsidian callouts
+
+Callouts are how the five information types stay visible while reading:
+
+```markdown
+> [!fact] Verified fact
+> Supported by a reviewed source.
+
+> [!hypothesis] Hypothesis
+> Requires validation.
+
+> [!warning] Needs verification
+> Do not publish or treat as canonical.
+
+> [!decision] Decision
+> Link to the decision-log entry.
+```
+
+## Navigation
+
+Start from `Home.md`. Every substantive note links back to at least one map,
+strategy, workstream or source note. A note nothing links to will not be found
+again, whatever the search index says.

whykit/template/README.md

@@ -0,0 +1,51 @@
+# Company knowledge vault
+
+This repository holds the reasoning behind how this company operates: durable
+context, the evidence behind claims, and the decisions that were actually taken —
+with the rationale that made them make sense at the time.
+
+It is built on [WhyKit](https://github.com/CometWeb-io/whykit).
+
+## Start here
+
+Open `Home.md`. It is the map of content and the entry point for every session,
+human or agent.
+
+## Before you write anything
+
+1. Read `AGENTS.md`. It is the contract everyone works under, and it ships with
+   questions this company has to answer for itself. Answer them first.
+2. Read the README in the directory you are about to write in.
+3. Check the note is not already covered somewhere canonical. Link, do not copy.
+
+## The rule that matters most
+
+Do not let these blur:
+
+| Type | Means |
+|---|---|
+| Verified fact | Supported by reviewed evidence, cited as `E-NNN` |
+| Decision | An authorized choice, recorded as `D-NNN`, never rewritten |
+| Hypothesis | Plausible, not demonstrated |
+| Recommendation | Proposed, not yet accepted |
+| Open question | A known unknown with an owner |
+
+An unsupported claim should not become company memory just because somebody —
+or some agent — wrote it confidently.
+
+## Checking your work
+
+```bash
+whykit lint
+whykit lint --strict
+```
+
+The linter checks shape, not truth. It will tell you that a claim has no
+evidence; it cannot tell you the evidence is any good.
+
+## Sensitivity
+
+Every note carries `sensitivity: public | internal | confidential | restricted`.
+**This vault is not public unless you have deliberately made it so.** Never lower
+a sensitivity label to make sharing easier, and never record a secret value —
+record where the secret lives and who can grant it.

whykit/template/assets/README.md

@@ -0,0 +1,6 @@
+# Assets
+
+Images and other attachments linked from notes. Reference them relatively.
+
+Name files after what they show, not after the tool that produced them. A
+directory of `screenshot-2026-09-17-at-14-03-22.png` is a directory of nothing.

whykit/template/reports/README.md

@@ -0,0 +1,7 @@
+# Reports
+
+Generated and recurring analyses. Every file ends with its date.
+
+A report is a snapshot: true on the day it was produced and never updated
+afterwards. When the analysis is re-run, add a new file. Overwriting a report
+destroys the only copy of what was true last month.

whykit/template/templates/README.md

@@ -0,0 +1,7 @@
+# Templates
+
+Reusable document structures. Every file here carries `status: template` and is
+never treated as content.
+
+Copy a template, do not link to it. Placeholders use `TODO` or an obvious
+`YYYY-MM-DD` so an unfilled document is visibly unfinished.

whykit/template/templates/automation-spec-template.md

@@ -0,0 +1,70 @@
+---
+title: Automation spec — workflow name
+aliases: []
+type: specification
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Automation spec: workflow name
+
+## Purpose
+
+## Trigger
+
+## Inputs
+
+| Field | Source | Required | Validation | Personal data |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## Logic
+
+1.
+
+## Outputs and side effects
+
+-
+
+## Systems involved
+
+-
+
+## Ownership
+
+- Business owner:
+- Technical owner:
+- Exception owner:
+
+Name a person for the exception owner. "The team" means nobody will notice the
+failure.
+
+## Error handling
+
+- Retry policy:
+- Alerting:
+- Manual fallback:
+- Rollback:
+
+## Monitoring
+
+| Metric / log | Threshold | Location | Owner |
+|---|---|---|---|
+|  |  |  |  |
+
+## Security and compliance
+
+- Access:
+- Data retention:
+- Consent / legal basis:
+- Secret management — where they live, never their values:
+
+## Acceptance criteria
+
+- [ ]

whykit/template/templates/decision-record-template.md

@@ -0,0 +1,65 @@
+---
+title: Decision record — title
+aliases: []
+type: decision
+decision_id: D-XXX
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Decision record: title
+
+## Decision ID
+
+D-XXX
+
+## Status
+
+Proposed / accepted / superseded
+
+## Context
+
+What was true when this came up, and what forced a choice.
+
+## Decision
+
+What was decided, in one sentence.
+
+## Rationale
+
+## Evidence
+
+-
+
+## Alternatives considered
+
+| Alternative | Upside | Risk | Why rejected |
+|---|---|---|---|
+|  |  |  |  |
+
+An empty row here means the decision was not really a choice. Either fill it or
+say plainly that there was only one option.
+
+## Consequences
+
+### Positive
+
+-
+
+### Negative and trade-offs
+
+-
+
+## Ownership and review
+
+- Owner:
+- Decided on:
+- Review on:
+- Supersedes:
+- Superseded by:

whykit/template/templates/document-template.md

@@ -0,0 +1,55 @@
+---
+title: Document title
+aliases: []
+type: guide
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Document title
+
+## Purpose
+
+Which decision or workflow does this document support?
+
+## Scope
+
+In scope:
+
+-
+
+Out of scope:
+
+-
+
+## Verified facts
+
+| Fact | Evidence |
+|---|---|
+|  |  |
+
+## Analysis
+
+Keep interpretation visibly separate from the evidence above.
+
+## Recommendations
+
+-
+
+## Decisions
+
+- None yet.
+
+## Open questions
+
+-
+
+## Related documents
+
+-

whykit/template/templates/experiment-template.md

@@ -0,0 +1,62 @@
+---
+title: Experiment — title
+aliases: []
+type: framework
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Experiment: title
+
+## Problem
+
+## Evidence
+
+-
+
+## Hypothesis
+
+We believe that [change] for [audience] will lead to [outcome], because [reason].
+
+## Primary metric
+
+One. An experiment with three primary metrics has none.
+
+## Guardrail metrics
+
+-
+
+## Baseline
+
+Needs verification. Record it before the experiment starts — a baseline measured
+afterwards is a description of the result.
+
+## Design
+
+- Variant / intervention:
+- Audience:
+- Duration or sampling rule:
+- Exclusions:
+
+## Decision rule
+
+What result leads to what action, written before the data arrives.
+
+## Result
+
+Not started.
+
+## Decision
+
+Pending.
+
+## If the hypothesis failed
+
+Say so here explicitly, and keep the record. A failed hypothesis that stays on
+file stops the same idea being proposed again next quarter.

whykit/template/templates/meeting-note-template.md

@@ -0,0 +1,47 @@
+---
+title: Meeting — topic
+aliases: []
+type: guide
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Meeting: topic
+
+- Date:
+- Attendees:
+- Purpose:
+
+## Context
+
+## Notes
+
+-
+
+## Decisions
+
+| Decision | Owner | Evidence / rationale | Decision-log ID |
+|---|---|---|---|
+|  |  |  |  |
+
+A decision recorded here is not yet recorded. Open `06-decisions/` and add it.
+
+## Actions
+
+| Action | Owner | Due | Tracked in |
+|---|---|---|---|
+|  |  |  |  |
+
+## Open questions
+
+-
+
+## Repository updates required
+
+-

whykit/template/templates/page-brief-template.md

@@ -0,0 +1,63 @@
+---
+title: Page brief — page name
+aliases: []
+type: specification
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Page brief: page name
+
+## Business goal
+
+## Primary audience
+
+## Visitor situation and intent
+
+What the visitor was doing immediately before arriving, and what they came to
+settle. A page written for a search query rather than a situation reads like a
+search query.
+
+## Primary conversion
+
+## Secondary conversion
+
+## Core message
+
+Needs verification.
+
+## Evidence the page must carry
+
+-
+
+## Questions the page must answer
+
+-
+
+## Proposed structure
+
+1.
+
+## Search and answer-engine inputs
+
+- Primary topic:
+- Supporting questions:
+- Entities:
+- Internal links:
+- Schema requirements:
+
+## Measurement
+
+| Event | Definition | Tool | Owner |
+|---|---|---|---|
+|  |  |  |  |
+
+## Dependencies and risks
+
+-

whykit/template/templates/research-note-template.md

@@ -0,0 +1,53 @@
+---
+title: Research note
+aliases: []
+type: research
+status: template
+owner: TODO
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+source_of_truth: false
+sensitivity: public
+source_ids: []
+tags: []
+---
+
+# Research note
+
+## Research question
+
+## Source
+
+- Title:
+- Author / organisation:
+- URL or repository path:
+- Published:
+- Accessed:
+- Evidence-register ID:
+
+## Key findings
+
+-
+
+## Direct evidence
+
+Paraphrase by default. Use short quotes only where the exact wording carries the
+meaning, and attribute them.
+
+## Limitations
+
+What this source cannot tell us, and where it is likely to be biased.
+
+-
+
+## Interpretation
+
+-
+
+## Implications
+
+-
+
+## Follow-up questions
+
+-