diff --git a/GITHUB_RELEASE_PREP.md b/GITHUB_RELEASE_PREP.md new file mode 100644 index 0000000..de9519e --- /dev/null +++ b/GITHUB_RELEASE_PREP.md @@ -0,0 +1,83 @@ +# GitHub Release Prep + +Recommendations for the GitHub repository's public-facing settings and the gate that +must pass before the repo goes public. **Nothing here is applied automatically** — a +human sets the GitHub fields and flips visibility. + +> The repository is still **PRIVATE**. Do not make it public until the Final Public +> Release Gate (below) passes and a human approves. + +## Recommended GitHub description + +``` +Local-first Engineering Intelligence for software repositories. +``` + +## Recommended GitHub topics + +``` +developer-tools +cli +software-engineering +code-intelligence +repository-analysis +local-first +static-analysis +engineering-intelligence +developer-productivity +architecture +technical-debt +python +sqlite +open-source +``` + +## Repo metadata fields (TODO) + +``` +Website: TODO +Demo video: TODO — upload devtime-demo-v0.0.8.mp4 after the repo becomes public, + then add the public link to README.md (## Demo) and the release notes. +``` + +Demo assets (local, not in the repo): +- Video: `devtime-demo-v0.0.8.mp4` (2:02, 1920×1080, silent/caption-driven) +- Thumbnail: `devtime-demo-thumbnail-v0.0.8.png` (1920×1080) + +--- + +## Final Public Release Gate + +All must be true before flipping the repo to public. Check, don't assume. + +- [ ] Repo visibility still **private** until final approval +- [x] Tests pass (88) +- [x] Clean-clone install works (see CLEAN_INSTALL_CHECK.md) +- [ ] Package version decision made (currently `0.0.7`; bump to `0.1.0` only at release) +- [ ] `v0.1.0` release tag **not** created until final approval +- [ ] README has the public demo link (currently a placeholder) +- [ ] Demo video uploaded somewhere public +- [x] Thumbnail ready (`devtime-demo-thumbnail-v0.0.8.png`) +- [x] LICENSE present (Apache-2.0) +- [x] Limitations visible (LIMITATIONS.md, linked from README) +- [x] Issue template present (`.github/ISSUE_TEMPLATE/devtime-got-this-wrong.yml`) +- [x] No local DB committed (`*.sqlite` ignored/absent) +- [x] No `.devtime/` committed +- [x] No secrets committed +- [x] No AI-authorship traces (project policy) +- [ ] GitHub description set (recommendation above) +- [ ] GitHub topics set (recommendation above) +- [ ] 5–10 reviewers completed, or final approval given +- [ ] Final clean-clone test completed on the release commit +- [ ] Release notes reviewed (RELEASE_NOTES_v0.1.0_DRAFT.md) +- [ ] Launch post reviewed (LAUNCH_POSTS.md) + +### Recommended release sequence (when approved) + +1. Decide the version (bump `pyproject.toml` + `__init__.py` to `0.1.0` if releasing as v0.1.0). +2. Upload the demo video publicly; replace the README `## Demo` placeholder with the link. +3. Final clean-clone test on the release commit. +4. Tag `v0.1.0`, push. +5. Flip repository visibility to **public**. +6. Publish the GitHub Release using RELEASE_NOTES_v0.1.0_DRAFT.md. +7. Post the launch messages (LAUNCH_POSTS.md). diff --git a/LAUNCH_POSTS.md b/LAUNCH_POSTS.md new file mode 100644 index 0000000..5cadffd --- /dev/null +++ b/LAUNCH_POSTS.md @@ -0,0 +1,91 @@ +# Launch Posts (drafts) + +Draft copy for the public launch. Honest, no hype. Pick/edit before posting. Replace +`` placeholders at launch. + +> Avoid: "revolutionary", "game-changing", "replaces developers", "AI understands your +> repo", "fully autonomous", "perfect". DevTime requires no AI and makes no such claims. + +## 1. X / Twitter (short) + +> DevTime: a local-first CLI that helps a codebase explain itself **from evidence**. +> +> It detects concepts, links every claim to files, and shows what the repo **can't** +> prove yet. Uncertainty is a feature, not a bug. +> +> No cloud. No telemetry. No code execution. No AI required. +> +> + +Alt one-liner: +> AI writes. EI remembers. DevTime is local-first repository memory from evidence — +> no cloud, no telemetry, no code execution, no AI required. + +## 2. LinkedIn + +> **DevTime — repository memory from evidence** +> +> Git remembers code. It doesn't remember *understanding* — why a behavior exists, +> what evidence supports it, or what nobody has decided yet. As AI tools generate code +> faster than teams can review it, that missing understanding becomes the bottleneck. +> +> DevTime is a local-first CLI that scans a repository and helps it explain itself from +> evidence: it detects concepts, links each claim to the files behind it, surfaces +> uncertainty when reasoning is missing, and gives an advisory, narrow risk review of a +> diff. Every claim links to evidence; weak evidence produces uncertainty, not +> confidence. +> +> What it is **not**: it doesn't execute your code, send anything to the cloud, use +> telemetry, or require AI. It's a heuristic tool with a closed set of concept families +> in V0 — and it's honest about its limits. +> +> No cloud. No telemetry. No code execution. No AI required. Apache-2.0. +> +> Try it on one repo and tell me what it gets wrong: + +## 3. Hacker News / Reddit-style intro + +> **Show: DevTime — a local-first CLI that helps a repo explain itself from evidence** +> +> I built DevTime because Git remembers code but not *understanding* — why something +> exists, what evidence supports it, what nobody decided yet. +> +> DevTime scans a repository locally (no network, no code execution) into a local +> SQLite store, detects a small set of concepts (Authentication, Billing Webhooks, +> Background Jobs, …), links every claim to the files behind it, and **shows +> uncertainty** when the reasoning isn't there. It can review a git diff for a narrow +> set of risky changes (advisory only), and it produces governed "Context Packs" for +> humans and agents. +> +> Design choices I care about: +> - Evidence decides. No claim without evidence; weak evidence → uncertainty. +> - Local-first: no cloud, no telemetry, no code execution, no AI required. +> - Honest about limits: a heuristic scanner with a closed six-concept ontology in V0, +> not a compiler and not a security tool. +> - "Uncertainty is a feature, not a bug." It shows what the repo can prove — and what +> it can't prove yet. +> +> It's Apache-2.0. I validated it privately on several large real repos and turned the +> wrong outputs into regression fixtures. Feedback — especially "it got this wrong" — +> is exactly what I'm looking for. +> +> Repo + 2-minute demo: + +--- + +## Private soft-launch message (5–10 reviewers / friends) + +> Hey — I'd love your eyes on **DevTime** before I make it public. It's a local-first +> CLI that helps a repo explain itself from evidence (no cloud, no telemetry, no code +> execution, no AI). ~15 minutes: +> +> 1. Clone the repo: `` +> 2. Follow **QUICKSTART.md** (install + `pytest`). +> 3. Watch the 2-minute demo video. +> 4. Run it on **one real repo** of yours: `dtc init && dtc scan && dtc concepts` then +> `dtc explain ""`. +> 5. If it gets anything wrong, open a **"DevTime got this wrong"** issue (there's a +> template). Wrong outputs are the most useful thing you can give me — they become +> regression fixtures. +> +> No pressure to be thorough — even one "this concept is wrong" report helps. Thanks! diff --git a/README.md b/README.md index a0bbfe1..71d7329 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,14 @@ The narrative: A full, copy-pasteable walkthrough is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**. +## Demo + +A 2-minute demo video is ready for public release. + +TODO before public launch: +- Upload `devtime-demo-v0.0.8.mp4` +- Add the public video link here + ## Installation Requires **Python ≥ 3.11** and git. diff --git a/RELEASE_NOTES_v0.1.0_DRAFT.md b/RELEASE_NOTES_v0.1.0_DRAFT.md new file mode 100644 index 0000000..f413b37 --- /dev/null +++ b/RELEASE_NOTES_v0.1.0_DRAFT.md @@ -0,0 +1,121 @@ +# DevTime v0.1.0 — Repository Memory From Evidence + +> **DRAFT.** This is a draft for the first public release. `v0.1.0` has **not** been +> tagged. Versions/links are finalized at release time. + +## 1. What is DevTime? + +DevTime is a **local-first Engineering Intelligence** CLI. It helps a repository +explain itself **from evidence**: it scans code, tests, configs, routes, and +decisions to identify the concepts inside a codebase, shows the evidence behind each +claim, surfaces uncertainty, and warns about a narrow set of risky changes. + +It does not execute your code, does not send your code anywhere, and does not require +AI. It does not pretend to know things without evidence. + +## 2. What works in this release + +- Local scan of a repository (no network, no code execution) into a local SQLite + memory store in `.devtime/`. +- Detection of **six** supported concept families (closed ontology — see below). +- Evidence-linked, strength-aware claims with explicit **uncertainty**. +- An **Understanding Score** (higher = better) and an **Understanding Debt** label. +- **Advisory, narrow** risk review of a git diff (e.g. JWT algorithm weakening; + billing-webhook retry without dedupe tests), with explicit result states. +- Governed, capped, evidence-based **Context Packs** for humans and agents. +- Local decision records that improve understanding **only when corroborated** by the + scanned implementation. + +## 3. Core commands + +``` +dtc init Create local .devtime memory. +dtc scan Scan the current repository (no code execution, no network). +dtc concepts List detected concepts with confidence and Understanding Debt. +dtc explain Explain a concept: claims, evidence, confidence, uncertainty, score. +dtc context Create a governed Context Pack for agents or humans. +dtc risk --diff Review a git diff for risky changes (advisory). +dtc decision add Record a decision that can reduce uncertainty when corroborated. +``` + +(Also: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`, `dtc export`, +`dtc reset`.) + +## 4. Trust model + +- Local repository memory in `.devtime/` (local SQLite). +- **No cloud. No telemetry. No code execution during scan. No AI required.** +- Ignored directories are pruned before scanning; ignored files and secrets are + excluded from evidence by design. +- Every claim links to evidence. Weak evidence produces uncertainty, not confidence. +- Risk review is **advisory** — it does not block PRs. + +## 5. Demo + +A ~2-minute demo video walks through a real scan on the sample app. + +*TODO at release:* upload the demo video and add the public link here. + +## 6. What changed during private validation + +DevTime was validated privately on real repositories (Langfuse, Cal.com, Open WebUI, +Plane, Twenty) across several review rounds. The output got **more honest**, not +larger: + +- File-local payment-provider evidence for Billing Webhooks (calendar/credential/ + generic webhooks no longer become Billing Webhooks). +- Word-sense gates (a job *title* is not a Background Job; an avatar *URL* is not a + File Upload; a `session_id` trace is not Authentication). +- Strength-aware claims; no contradictory "is present" for weak evidence. +- Explicit risk-review states (`review_failed`/`no_findings`/`unsupported_change_class`/ + `finding`); a git failure is never reported as "no findings". +- Decisions must be corroborated by the code to clear uncertainty or raise the score. +- Context Pack reasons are truthful and auditable (import / same-directory, or omit). + +## 7. Known limitations + +DevTime is a **heuristic scanner**, not a compiler or semantic analyzer. It uses a +**closed six-concept ontology** (Authentication, Billing Webhooks, Background Jobs, +Data Export, Admin Permissions, File Uploads) and does not discover arbitrary domain +concepts. It is strongest on TypeScript/Next.js/Express/FastAPI-style repos. Risk +review covers a **narrow** set of change classes and is advisory. False positives and +negatives are possible. No git-history signals, no wired MCP transport, no AI provider, +no UI, no cloud. See [LIMITATIONS.md](LIMITATIONS.md). This is **not** a production-ready +enterprise platform or a broad security review. + +## 8. Install + +Requires Python ≥ 3.11 and git. + +``` +git clone +cd devtime +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -e ".[dev]" +pytest # 88 tests +``` + +## 9. Try the demo repo + +``` +cd examples/demo-saas +dtc init +dtc scan +dtc concepts +dtc explain "Billing Webhooks" +``` + +See QUICKSTART.md and DEMO_SCRIPT.md for the full walkthrough (including the risk-diff +and corroborated-decision steps). + +## 10. Feedback wanted + +If DevTime gets something wrong on your repo, that's the most useful feedback — open a +**"DevTime got this wrong"** issue (template included). Wrong outputs become fixtures +so they can't silently regress. + +--- + +Licensed under **Apache-2.0**. Local-first. Honest about uncertainty, honest about +limits.