jearless 0.10.4__tar.gz

jearless-0.10.4/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

jearless-0.10.4/.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/AndrewZakh/auto-version-hook
+    rev: v1.1.0
+    hooks:
+      - id: auto-version

jearless-0.10.4/.version-hook.yml

@@ -0,0 +1,49 @@
+---
+# jearless × auto-version-hook: the version lives in env.yml and rides the
+# feature branch. The README invariant ("main moves only by merges") holds:
+# main is protected, merge commits are skipped, the bump happens in the branch.
+
+version:
+  file: env.yml
+  key: version
+  parse_regex: '^v(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'
+
+# The package version mirrors the flow version (auto-version-hook v1.1.0):
+# after every bump both move together; no v-prefix here (PEP 440 style).
+version_files:
+  - path: pyproject.toml
+    regex: '^version = "(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"$'
+
+git:
+  remote: origin
+  fetch: true
+
+branch_flow:
+  - name: main
+    regex: '^main$'
+    protected: true    # a direct commit to main never bumps the version
+    policy: keep
+
+  - name: feature
+    regex: '^feature/' # feature/<project>/<id>-<slug> — the whole README taxonomy
+    target: main
+    policy: increment
+    bump: minor
+    reset_lower_parts: false
+
+  - name: fix
+    regex: '^fix/'
+    target: main
+    policy: increment
+    bump: patch
+    reset_lower_parts: false
+
+  - name: chore
+    regex: '^chore/'
+    target: main
+    policy: ignore
+
+hooks:
+  auto_stage: true
+  on_error: fail
+  skip_merges: true    # does not act on merge commits — the charter moves those

jearless-0.10.4/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+## v0.10.4 (2026-11-07)
+### Added
+- tooling-10: add — duplicate guard: keyword-overlap warning and confirmation
+# 1 off-taxonomy merge(s) skipped — the visible hole (README)
+
+## v0.9.4 (2026-11-07)
+### Added
+- tooling-1: add — append a task to the registry
+- tooling-2: take — claim a task with a single push
+- tooling-3: sprint — a join of three sources
+- tooling-4: changelog — a generator over merge commits
+- tooling-5: doctor — the visible hole
+- tooling-6: timeline — live and snapshot
+- tooling-7: retro — plan versus actual
+- tooling-9: release step — tag, changelog and timeline snapshot in one move
+# 8 off-taxonomy merge(s) skipped — the visible hole (README)

jearless-0.10.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AndrewZakh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jearless-0.10.4/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: jearless
+Version: 0.10.4
+Summary: Fearless. Jearless. Task tracking and a changelog on bare git — for small teams.
+Project-URL: Homepage, https://github.com/AndrewZakh/jearless
+Project-URL: Repository, https://github.com/AndrewZakh/jearless
+Project-URL: Changelog, https://github.com/AndrewZakh/jearless/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/AndrewZakh/jearless/issues
+Author: Andrei Zakhrebetkov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: changelog,cli,git,issue-tracker,task-tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: ruamel-yaml>=0.18
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jearless
+
+**Fearless. Jearless.** Task tracking and a changelog on bare git — for small teams.
+
+*Why the name: by ear — a faint echo of Jira; by sight — fearless; spelled with an error — and we track errors for a living; a jearless sprint — a fast run without fat.*
+
+## Install
+
+From PyPI, straight into an isolated environment:
+
+```sh
+pipx install jearless        # the intended way for daily use
+```
+
+For development, one command builds the venv with everything. There is
+deliberately **no requirements.txt**: `pyproject.toml` is the single authored
+source of dependencies, and a second list would drift.
+
+```sh
+uv venv && uv pip install -e ".[dev]"                          # uv
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"     # plain pip
+```
+
+## Quickstart
+
+Inside your git repository:
+
+```sh
+jear add door "paint it black" --points 2   # a task in the eternal registry
+jear take door 1                            # branch feature/door/1-paint-it-black, pushed
+# ... work, then a true merge (--no-ff) ...
+jear sprint                                 # available / in_progress / done — derived from git
+```
+
+No statuses are ever stored: the registry holds frozen facts, git holds
+everything alive. See [The idea](#the-idea) for the full model.
+
+**Status:** the design has stabilized; the mechanism is built around the eternal registry; the name is settled — jearless (2026-11-06). This file records the decisions and their rationale — it is not a specification. The implementation plan lives in [PLAN.md](PLAN.md).
+
+## The idea
+
+Task tracking and a changelog on bare git. No trackers, no infrastructure.
+
+1. `tasks.yml` — the **eternal task registry**: subproject, id, summary, description, story_points. Tasks are added and never deleted; the file only grows. No live-state fields.
+2. `jear take door_design 16` — zero commits, zero YAML edits: verify the branch is absent on origin, create `feature/door_design/16-slug`, push. **Taking a task = pushing the branch.**
+3. Merging is a true merge (`--no-ff`): the branch name lands in history through the merge commit. No squash, no rebase merges.
+4. The changelog is not stored — it is generated at release time: merge commits between tags → the regex from the config → the line template. The line is the summary from the registry or the slug from the branch name.
+5. The branch prefix (`feature/`, `fix/`, `chore/`) → the changelog section.
+
+## The state model: three sources, zero stored statuses
+
+| State | Condition |
+|---|---|
+| available | present in tasks.yml ∧ no branch on origin ∧ no merge commit |
+| in_progress | a branch exists on origin ∧ no merge commit |
+| done | a merge commit carrying the branch name exists in main (overrides an existing branch when the forge's auto-delete is off) |
+
+The sprint and all analytics are joins on the key (subproject, number), computed on demand. The race for a task is arbitrated by git itself: a second push of a branch with the same name is rejected as non-fast-forward — "taken" arrives from the server.
+
+## Timeline and plan-versus-actual
+
+- **The actual timeline** is a derived view: start = author date of the branch's first commit, end = committer date of the merge commit. The live variant is a command run on demand (fetch --prune, open branches end "now") and is **never committed**. The release snapshot is frozen by the tag and committed next to the changelog.
+- **The Gantt (the plan)** is an authored artifact: drawn by hand or by script, committed as the team's contract. For the retrospective comparison, **bar ids = task ids** (subproject + number) — otherwise the plan cannot be joined with the facts.
+- The hierarchy of truth about the start: the branch's first commit (exact, eternal) → merge-base (skewed by main's stagnation: the common commit's date ≠ the cut date) → forge events (the push time is visible, but the feed expires — on GitHub, within about 90 days). Push time does not exist in git's object model.
+- Activity time metrics (hours, commit-clock deadlines) are deliberately out of scope: commit dates are client clocks, trivially spoofed, and they invite gaming.
+
+## Key decisions
+
+- **The number is an identifier, not a position.** No renumbering, no reuse; the uniqueness key is the pair (subproject, number). Allocating the next number looks only at the registry — it never empties and never shrinks.
+- **The eternal registry instead of deletion:** the old mechanics — "the task's deletion rides the branch's first commit" — is cancelled. Consequences: the task card (story_points included) lives forever, so analytics over done tasks lose nothing; `take` never mutates the YAML, so the yq round-trip problem disappears; registry conflicts become nearly impossible — only simultaneous additions at the same spot.
+- **The branch name is the only key** linking the registry, the changelog and history. Slashes are the structural separators (`feature/door_design/16-slug`); hyphens live only inside slugs.
+- **YAML as the registry format:** readable by yq, analytics over frozen facts. Live-state fields (status and friends) are forbidden: git knows the state, a stored copy drifts. Scripts only read the registry (`add` appending is the sole sanctioned exception).
+- **The language of the registry, slugs and changelog is English** (the GitHub norm; decided 2026-11-06). Transliteration is only a fallback inside `take`, for summaries not written in latin script — a last resort for those who skipped their lessons, not the project's style.
+- **main moves by merges only — no squash, no rebase merges, always `--no-ff`.** Direct human commits (add a task, fix the plan) are allowed; the ban concerns automatic writers and merge methods. Rebasing inside one's own unmerged branch is harmless — author dates survive it.
+- **Nothing automatic writes to main.** Dropping a task = deleting the branch = the task is available again (it never left the registry).
+- **"A separate life for the registry" is rejected** (a submodule, a database rendered into yml, a secrets manager): moving the storage does not solve the trigger problem — who flips `done` after the merge. The principle: **state for an event that cannot be observed without infrastructure is never stored — it is derived.**
+- **Taking a task is a branch push: an occupancy registry, not a notification** — others see it at their own fetch.
+
+## Pros
+
+- One database — git history plus the eternal registry of facts. Zero state files, zero hooks with write access, zero CI jobs pushing to main.
+- Taking a task is one push, zero commits; undoing it is deleting the branch.
+- The task card lives in the registry forever: velocity and any analytics over done tasks lose no data.
+- The race for a task is resolved by the server, atomically, without locks or queues.
+- Plan-versus-actual from two honest sources: the plan is authored and committed, the actual is derived from git, the comparison is the retrospective.
+- Branch prefixes are the taxonomy: "Added / Fixed" sections come for free.
+- Merge commits make a task an object of history: `--merges` between tags is the task journal; a merge commit's diff is the whole task at once.
+- Version binding is free: whatever is merged between v1.2 and v1.3 lands under the v1.3 heading.
+- The registry is versioned with the code, reviewed in merges, available offline.
+
+## Cons / risks
+
+- **Squash and rebase merges silently lose the branch name** — the changelog line disappears without an error. On the forge these are the two enemy buttons; the repo needs "Create a merge commit" as the default. The legitimate way to clean up a task's history is **squash inside the branch before the true merge** ("squash inside, merge outside"): compress the WIP into one commit preserving the first commit's author date, then `--no-ff`. Verified by a live demo, 2026-11-06: the key lives in the merge commit, the timeline start in the preserved author date.
+- **Fast-forward is the default** and the sneakiest source of lost merge commits: when main has not moved, git just moves the pointer. The "always --no-ff" rule is easy to forget.
+- **The regex in the config rots first** (the very first draft failed to match its own example). A generator dry-run is mandatory.
+- The regex must digest both merge message forms: "Merge branch ..." and "Merge pull request #N from owner/...".
+- **YAML under hand editing:** block scalars for long descriptions are the most finicky spot; on-the-fly validation is mandatory.
+- **Registry growth:** the file only increases. A measurement (2026-11-06, synthetic, ~270 bytes per task): a filtered query over 1M tasks (270 MB) takes 20 s with slow ruby/libyaml and 2 s with jq; a full minute arrives at ~3–30 million tasks — outside human scales. The real archivation trigger is ergonomics (scrolling the file, bloated diffs), not query speed.
+- **available is a three-way join with negation** (in the registry ∧ no branch ∧ no merge commit): easy to get wrong — hence exactly one canonical implementation.
+- **The start of a bar ≠ the birth of the branch:** merge-base is skewed by main's stagnation; the forge event feed expires; git does not store push time. The only eternal starting point is the branch's first commit.
+- **Local origin/* refs are a cache, not the truth:** without `fetch --prune`, ghosts of deleted branches keep tasks "taken" forever.
+- Only single-line changelog entries; multi-paragraph ones are a backup path of towncrier-style fragments.
+- The insurance against someone else's squash/rebase is **a task trailer in the commit message** (`Task: door_design/16`; modern gits even have `git commit --trailer`): it rides in the object itself and survives a squash if it made it into the squash message. git notes and refs/replace were rejected as metadata channels: they do not travel with a default clone/fetch and forges do not show them. When a squash has already happened, the key cannot be attached retroactively (amend would rewrite main) — which is why the generator's dry-run must highlight unattributed commits loudly: the hole must be visible, not silent.
+- The applicability boundary: the moment you need labels, assignees or task discussion — move to Issues, do not build a hybrid. Jira earns its keep for large teams and corporate scale; jearless is for the small and the swift.
+
+## Open questions
+
+- The generator config: the regex + the line template + the prefix-to-section mapping; the dry-run format.
+- How to hard-wire the fast-forward ban (an alias, a setting, a check inside `take`).
+- Branches that miss the regex (quick fixes without a task) — a filter feature or a hole?
+- Auto-deleting branches on the forge after a merge — the generator must not rely on the branch still existing.
+- Archiving `tasks.yml`: the trigger is ergonomic discomfort, not performance. Rules for the future: cut by release tag (the same frozen moment as the changelog and the timeline snapshot), the file `archive_<tag>.yml`, move out done tasks only; available/in_progress are always computed over tasks.yml, identity for analytics is the union of the registry and the archives; it is a release-time step run by a human. The script itself is a registry task, to be taken when the trigger fires.

jearless-0.10.4/PLAN.md

@@ -0,0 +1,44 @@
+# Implementation plan
+
+Date: 2026-11-06. The design lives in README.md (the project constitution — argued and proven). This file is how we build it. The name is settled: **jearless**. Package `jearless`, console command `jear` (alias `jearless`), config `.jearless.toml`. Slogan: "Fearless. Jearless. Bare git is enough — for small teams."
+
+## Technical decisions (and why)
+
+- **Python 3.11+, installed via pipx.** One dependency — ruamel.yaml. Everything else is stdlib.
+- **Git via subprocess.** Zero dependencies and full flag transparency. GitPython drags in gitdb and hides parameters — and our tool is precisely about the exact semantics of git; hiding it is out of the question.
+- **Versioning via auto-version-hook** (pre-commit, pinned `v1.1.0`, config `.version-hook.yml`): the version bump rides the feature branch, main is protected, merge commits are untouched (`skip_merges`) — the "main moves only by merges" invariant holds. The flow version lives in `env.yml`; the package version in pyproject mirrors it automatically (`version_files`, hook v1.1.0).
+- **CLI on argparse.** The tool preaches minimalism — let the framework count be zero.
+- **ruamel.yaml (rt mode) — the only YAML parser.** Edits preserve comments (closes the round-trip risk from the README); reads use it too — the files are kilobytes, and the 2026-11-06 measurement showed performance is a non-issue at any scale.
+- **Tests are repository factories in temporary directories** (the pattern of our /tmp demos) plus golden files for the generator. No git mocks — only real repositories with real merges.
+- **The config is `.jearless.toml`:** the branch regex, the changelog line template, the prefix-to-section mapping.
+
+## The CLI surface (mapped to the README)
+
+| Command | Mechanics | Phase |
+|---|---|---|
+| `add <project> "summary" [--points N] [--yes]` | append a task to the registry (comments survive); next id = max over registry ∧ archives ∧ branches; the duplicate guard warns on keyword overlap and asks `y/N` (non-TTY declines, `--yes` skips) | 1 |
+| `take <project> <id>` | registry → slug; check origin (ls-remote — the truth, not the cache); branch `feature/<project>/<id>-<slug>`; push. The server arbitrates the race | 1 |
+| `sprint` | fetch --prune; the join registry × origin branches × merge log; states available / in_progress / done | 1 |
+| `changelog --from <tag> --to <tag> --dry-run` | merge commits → the config regex → sections by prefix; the summary from the registry (union with archives) | 2 |
+| `doctor` | unattributed commits on main (neither merges nor registry edits) — the visible hole; branch naming violations; an invalid registry | 2 |
+| `timeline --live \| --snapshot <tag>` | a mermaid gantt of the facts; live is never committed; the snapshot is a release artifact | 3 |
+| `retro <plan.md>` | join the plan's bar ids (the gantt contract) with the actual timeline; planning misses | 3 |
+| `archive <tag>` | move done tasks into `archive_<tag>.yml` — only on the ergonomics trigger | 4 |
+| `release [--tag TAG]` | tag + changelog section + timeline snapshot in one human-run move; the tag defaults to the env.yml flow version; artifacts are committed and the annotated tag lands on them | — |
+
+## Phases and Definitions of Done
+
+- **Phase 0. Skeleton:** pyproject, the CLI frame, the config schema, the git wrapper (subprocess), lint. DoD: `--help` works; empty states (no tags, no branches, an empty registry) do not crash commands.
+- **Phase 1. The core loop:** add + take + sprint. DoD: a task is taken with a single push; the sprint is assembled from three sources; the race test — two takes from two clones against one remote, the second one gets "taken"; deleting a branch returns the task to available.
+- **Phase 2. The journal:** changelog + doctor. DoD: golden tests on a factory repository with both merge message forms ("Merge branch …" and "Merge pull request …"); a squash commit is highlighted by doctor; dry-run is the default mode.
+- **Phase 3. Time:** timeline live/snapshot + retro. DoD: the snapshot carries the author date of the branch's first commit and the committer date of the merge; a plan with task ids joins with the facts.
+- **Phase 4. Deferred (on trigger):** archive, velocity analytics over the union of the registry and the archives.
+
+## What is deliberately absent (and that is a feature)
+
+Statuses and assignees (derived, not stored), CI integrations, a web UI, daemons, hooks, notifications. The moment those are needed — time to leave for Issues / git-bug / Backlog.md, not to build them in here.
+
+## Open implementation questions
+
+- `take` for a task missing from the registry: refuse, or an `--adhoc` flag — this would also settle the "branches off the regex" question.
+- Detecting a fast-forward retroactively is impossible (it leaves no trace) — doctor catches only unattributed commits.

jearless-0.10.4/README.md

@@ -0,0 +1,112 @@
+# jearless
+
+**Fearless. Jearless.** Task tracking and a changelog on bare git — for small teams.
+
+*Why the name: by ear — a faint echo of Jira; by sight — fearless; spelled with an error — and we track errors for a living; a jearless sprint — a fast run without fat.*
+
+## Install
+
+From PyPI, straight into an isolated environment:
+
+```sh
+pipx install jearless        # the intended way for daily use
+```
+
+For development, one command builds the venv with everything. There is
+deliberately **no requirements.txt**: `pyproject.toml` is the single authored
+source of dependencies, and a second list would drift.
+
+```sh
+uv venv && uv pip install -e ".[dev]"                          # uv
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"     # plain pip
+```
+
+## Quickstart
+
+Inside your git repository:
+
+```sh
+jear add door "paint it black" --points 2   # a task in the eternal registry
+jear take door 1                            # branch feature/door/1-paint-it-black, pushed
+# ... work, then a true merge (--no-ff) ...
+jear sprint                                 # available / in_progress / done — derived from git
+```
+
+No statuses are ever stored: the registry holds frozen facts, git holds
+everything alive. See [The idea](#the-idea) for the full model.
+
+**Status:** the design has stabilized; the mechanism is built around the eternal registry; the name is settled — jearless (2026-11-06). This file records the decisions and their rationale — it is not a specification. The implementation plan lives in [PLAN.md](PLAN.md).
+
+## The idea
+
+Task tracking and a changelog on bare git. No trackers, no infrastructure.
+
+1. `tasks.yml` — the **eternal task registry**: subproject, id, summary, description, story_points. Tasks are added and never deleted; the file only grows. No live-state fields.
+2. `jear take door_design 16` — zero commits, zero YAML edits: verify the branch is absent on origin, create `feature/door_design/16-slug`, push. **Taking a task = pushing the branch.**
+3. Merging is a true merge (`--no-ff`): the branch name lands in history through the merge commit. No squash, no rebase merges.
+4. The changelog is not stored — it is generated at release time: merge commits between tags → the regex from the config → the line template. The line is the summary from the registry or the slug from the branch name.
+5. The branch prefix (`feature/`, `fix/`, `chore/`) → the changelog section.
+
+## The state model: three sources, zero stored statuses
+
+| State | Condition |
+|---|---|
+| available | present in tasks.yml ∧ no branch on origin ∧ no merge commit |
+| in_progress | a branch exists on origin ∧ no merge commit |
+| done | a merge commit carrying the branch name exists in main (overrides an existing branch when the forge's auto-delete is off) |
+
+The sprint and all analytics are joins on the key (subproject, number), computed on demand. The race for a task is arbitrated by git itself: a second push of a branch with the same name is rejected as non-fast-forward — "taken" arrives from the server.
+
+## Timeline and plan-versus-actual
+
+- **The actual timeline** is a derived view: start = author date of the branch's first commit, end = committer date of the merge commit. The live variant is a command run on demand (fetch --prune, open branches end "now") and is **never committed**. The release snapshot is frozen by the tag and committed next to the changelog.
+- **The Gantt (the plan)** is an authored artifact: drawn by hand or by script, committed as the team's contract. For the retrospective comparison, **bar ids = task ids** (subproject + number) — otherwise the plan cannot be joined with the facts.
+- The hierarchy of truth about the start: the branch's first commit (exact, eternal) → merge-base (skewed by main's stagnation: the common commit's date ≠ the cut date) → forge events (the push time is visible, but the feed expires — on GitHub, within about 90 days). Push time does not exist in git's object model.
+- Activity time metrics (hours, commit-clock deadlines) are deliberately out of scope: commit dates are client clocks, trivially spoofed, and they invite gaming.
+
+## Key decisions
+
+- **The number is an identifier, not a position.** No renumbering, no reuse; the uniqueness key is the pair (subproject, number). Allocating the next number looks only at the registry — it never empties and never shrinks.
+- **The eternal registry instead of deletion:** the old mechanics — "the task's deletion rides the branch's first commit" — is cancelled. Consequences: the task card (story_points included) lives forever, so analytics over done tasks lose nothing; `take` never mutates the YAML, so the yq round-trip problem disappears; registry conflicts become nearly impossible — only simultaneous additions at the same spot.
+- **The branch name is the only key** linking the registry, the changelog and history. Slashes are the structural separators (`feature/door_design/16-slug`); hyphens live only inside slugs.
+- **YAML as the registry format:** readable by yq, analytics over frozen facts. Live-state fields (status and friends) are forbidden: git knows the state, a stored copy drifts. Scripts only read the registry (`add` appending is the sole sanctioned exception).
+- **The language of the registry, slugs and changelog is English** (the GitHub norm; decided 2026-11-06). Transliteration is only a fallback inside `take`, for summaries not written in latin script — a last resort for those who skipped their lessons, not the project's style.
+- **main moves by merges only — no squash, no rebase merges, always `--no-ff`.** Direct human commits (add a task, fix the plan) are allowed; the ban concerns automatic writers and merge methods. Rebasing inside one's own unmerged branch is harmless — author dates survive it.
+- **Nothing automatic writes to main.** Dropping a task = deleting the branch = the task is available again (it never left the registry).
+- **"A separate life for the registry" is rejected** (a submodule, a database rendered into yml, a secrets manager): moving the storage does not solve the trigger problem — who flips `done` after the merge. The principle: **state for an event that cannot be observed without infrastructure is never stored — it is derived.**
+- **Taking a task is a branch push: an occupancy registry, not a notification** — others see it at their own fetch.
+
+## Pros
+
+- One database — git history plus the eternal registry of facts. Zero state files, zero hooks with write access, zero CI jobs pushing to main.
+- Taking a task is one push, zero commits; undoing it is deleting the branch.
+- The task card lives in the registry forever: velocity and any analytics over done tasks lose no data.
+- The race for a task is resolved by the server, atomically, without locks or queues.
+- Plan-versus-actual from two honest sources: the plan is authored and committed, the actual is derived from git, the comparison is the retrospective.
+- Branch prefixes are the taxonomy: "Added / Fixed" sections come for free.
+- Merge commits make a task an object of history: `--merges` between tags is the task journal; a merge commit's diff is the whole task at once.
+- Version binding is free: whatever is merged between v1.2 and v1.3 lands under the v1.3 heading.
+- The registry is versioned with the code, reviewed in merges, available offline.
+
+## Cons / risks
+
+- **Squash and rebase merges silently lose the branch name** — the changelog line disappears without an error. On the forge these are the two enemy buttons; the repo needs "Create a merge commit" as the default. The legitimate way to clean up a task's history is **squash inside the branch before the true merge** ("squash inside, merge outside"): compress the WIP into one commit preserving the first commit's author date, then `--no-ff`. Verified by a live demo, 2026-11-06: the key lives in the merge commit, the timeline start in the preserved author date.
+- **Fast-forward is the default** and the sneakiest source of lost merge commits: when main has not moved, git just moves the pointer. The "always --no-ff" rule is easy to forget.
+- **The regex in the config rots first** (the very first draft failed to match its own example). A generator dry-run is mandatory.
+- The regex must digest both merge message forms: "Merge branch ..." and "Merge pull request #N from owner/...".
+- **YAML under hand editing:** block scalars for long descriptions are the most finicky spot; on-the-fly validation is mandatory.
+- **Registry growth:** the file only increases. A measurement (2026-11-06, synthetic, ~270 bytes per task): a filtered query over 1M tasks (270 MB) takes 20 s with slow ruby/libyaml and 2 s with jq; a full minute arrives at ~3–30 million tasks — outside human scales. The real archivation trigger is ergonomics (scrolling the file, bloated diffs), not query speed.
+- **available is a three-way join with negation** (in the registry ∧ no branch ∧ no merge commit): easy to get wrong — hence exactly one canonical implementation.
+- **The start of a bar ≠ the birth of the branch:** merge-base is skewed by main's stagnation; the forge event feed expires; git does not store push time. The only eternal starting point is the branch's first commit.
+- **Local origin/* refs are a cache, not the truth:** without `fetch --prune`, ghosts of deleted branches keep tasks "taken" forever.
+- Only single-line changelog entries; multi-paragraph ones are a backup path of towncrier-style fragments.
+- The insurance against someone else's squash/rebase is **a task trailer in the commit message** (`Task: door_design/16`; modern gits even have `git commit --trailer`): it rides in the object itself and survives a squash if it made it into the squash message. git notes and refs/replace were rejected as metadata channels: they do not travel with a default clone/fetch and forges do not show them. When a squash has already happened, the key cannot be attached retroactively (amend would rewrite main) — which is why the generator's dry-run must highlight unattributed commits loudly: the hole must be visible, not silent.
+- The applicability boundary: the moment you need labels, assignees or task discussion — move to Issues, do not build a hybrid. Jira earns its keep for large teams and corporate scale; jearless is for the small and the swift.
+
+## Open questions
+
+- The generator config: the regex + the line template + the prefix-to-section mapping; the dry-run format.
+- How to hard-wire the fast-forward ban (an alias, a setting, a check inside `take`).
+- Branches that miss the regex (quick fixes without a task) — a filter feature or a hole?
+- Auto-deleting branches on the forge after a merge — the generator must not rely on the branch still existing.
+- Archiving `tasks.yml`: the trigger is ergonomic discomfort, not performance. Rules for the future: cut by release tag (the same frozen moment as the changelog and the timeline snapshot), the file `archive_<tag>.yml`, move out done tasks only; available/in_progress are always computed over tasks.yml, identity for analytics is the union of the registry and the archives; it is a release-time step run by a human. The script itself is a registry task, to be taken when the trigger fires.

jearless-0.10.4/env.yml

@@ -0,0 +1,4 @@
+# Flow version (auto-version-hook dogfood): bumped automatically in branches,
+# reaches main only by merge. The package version in pyproject.toml mirrors
+# this one automatically (version_files, hook v1.1.0).
+version: v0.10.4