application-pipeline 0.6.0__tar.gz

application_pipeline-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,103 @@
+name: Publish
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e '.[dev]'
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -m "not smoke"
+
+  build:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build setuptools-scm
+
+      - name: Compute version
+        id: version
+        run: |
+          VERSION=$(python -m setuptools_scm)
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_APPLICATION_PIPELINE=$VERSION" >> "$GITHUB_ENV"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Reject dev version on tag
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if [[ "$VERSION" == *.dev* ]]; then
+            echo "Error: tag build produced a dev version: $VERSION"
+            exit 1
+          fi
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: [test, build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: [test, build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

application_pipeline-0.6.0/.gitignore

@@ -0,0 +1,215 @@
+*.idea
+*.claude
+pycastle/
+synched/
+
+# Deduplication store — durability via Syncthing per ADR-0010
+.seen.json
+
+# 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
+.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
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# 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 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

application_pipeline-0.6.0/.python-version

@@ -0,0 +1 @@
+3.11.3

application_pipeline-0.6.0/CLAUDE.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in GitHub Issues on `Johannes-Kutsch/application-pipeline` via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Uses the five canonical triage label names as-is (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

application_pipeline-0.6.0/CONTEXT.md

@@ -0,0 +1,132 @@
+# Application Pipeline
+
+Personal job-discovery and triage pipeline. Fetches listings from a small set of sources, classifies relevance with Claude, accumulates an in-domain **Pool** across days, emits one dated **Daily Results File** per day carrying the **Daily Top-5** **Cards** ranked by the **Match Judge**. Application authoring (CV/cover letter) is out of scope for v1.
+
+## Scope
+
+- **In scope (v1):** Working **Parsers** for **Bundesagentur**, **stellen.hamburg**, **jobs-beim-staat**, smoke-tested standalone on the laptop.
+- **In scope (v1.1):** Full pipeline on Pi — orchestrator, **Relevance Classifier** (producing **Structured Extracts**), **Match Judge** (one call per run, picks **Daily Top-5** from the **Pool**), **Deduplication**, daily file, cron once per day, Syncthing sync.
+- **Out of scope:** **CV** / **Cover Letter** generation, LaTeX pipeline, **Profile** ingestion, additional commercial parsers, browser automation.
+
+## Language
+
+### Pipeline artifacts
+
+**Config**: A `config.py` at the root of the settings directory the user picks at `init` time (conventionally `~/application-pipeline/`) controlling the search — `KEYWORDS`, `SKILLS`, `NEGATIVE_KEYWORDS`, `SOURCES`, `LOCATIONS`, `INCLUDE_REMOTE`, `USER_INFO_DIR`, layout-path override, Claude settings (`claude_classify_batch_size: int` default 100, optional `claude_cli_path`), and `MAX_LISTING_AGE_DAYS: int` (default 180, `≥ 1`) driving the **Freshness Gate**'s `posted_date` arm. Plain Python literals; `#` comments. Materialised on first bootstrap from `src/application_pipeline/templates/config.py` via `application-pipeline init <dir>` (ADR-0011); the user edits in place from then on. Loaded by **Config Loader**, returns a frozen typed `Config`. `KEYWORDS` applies to every **Source** (Cartesian product over keyword × source); **Deduplication** absorbs overlap. Each `SourceEntry` carries its own `max_results` (default 1000). `NEGATIVE_KEYWORDS` entries validate to length ≥ 3. Cron schedule lives in crontab, not Config (ADR-0024, once daily at 00:30 local). _Avoid_: config file, settings file, search config.
+
+**Layout**: A `layout.py` alongside **Config**, owning user-tunable cosmetic/structural choices for the **Daily Results File**. Seeded from `src/application_pipeline/templates/layout.py` by `init`. Named placeholder groups + a single `CARD_TEMPLATE` (no per-tier dispatch — **Match Tier** retired per ADR-0020). Placeholder set excludes `emoji`/`color`/`tier`, includes `rank` (1..5). Loaded by `load_user_module`, validated into a frozen `Layout`. The **Renderer** substitutes placeholders via `str.format_map`. `LayoutError` subclasses `UserSettingsError` (shared with `ConfigError`). _Avoid_: style file, theme file, template file.
+
+**Daily Results File**: One dated markdown file per calendar day at `<settings-dir>/results/YYYY-MM-DD.md`, holding the **Daily Top-5** as **Cards** in **Rank** order. Date is **cron-anchored** (ADR-0021/0023) — a run started day X writes to day X's file even if it crosses midnight sleeping through quota. No `FILE_HEADER`, no preamble, no **Run Divider**. If today's pool had fewer than 5, the file carries however many cards; if pool was empty, no file is written. Write-once on the host; if a sync channel is configured (e.g. Syncthing), the file propagates outward read-only. _Avoid_: results file (without "daily"), `current.md` (gone), dated results file.
+
+**Failure Report**: A markdown file at `<settings-dir>/failures/<timestamp>.md` written on a failed run — `cron.sh` pip-upgrade errors (ADR-0027), orchestrator runtime errors, **Match Judge** failure (no daily file), and non-quota classifier errors that left the run with no writeable output. Per ADR-0010. Acknowledged by deleting the file. Quota errors do NOT trigger a Failure Report — they sleep until reset (ADR-0023). _Avoid_: incident report, error log.
+
+**Position**: A single job listing surviving the **Relevance Classifier** and the **Match Judge**'s top-5 selection. Identified within its **Daily Results File** by its rendered H1 (`# {company} · {title} · {location_segment}`); the explicit `{rank}` placeholder carries ordering. _Avoid_: job, listing, vacancy.
+
+**Position Schema**: The frozen-dataclass shape every **Parser** must return from `enrich()` — `Position(stub: PositionStub, raw_description: str, ...)` with optional `salary: str | None` (free string — German pay grades like `"E13 TV-L"` preserved verbatim), `contract_type: Literal["permanent","fixed-term","freelance"] | None`, `employment_type: Literal["full-time","part-time","internship"] | None`, `work_model: Literal["remote","hybrid","on-site"] | None`, `posted_date: date | None`, `deadline: date | None`. Closed-enum fields are `None` when the source exposes no signal — parsers never guess. `Position` *contains* its `PositionStub` (composition); fields reach consumers as `position.stub.<field>` (required: `url, title, source`; `company, location` are `str | None`). Both dataclasses live in `parsers/types.py` (parsers don't import from consumers). Both `frozen=True`, never mutated. Not persisted across runs — reconstructed by `Parser.enrich(stub)` each day for Pool items. The **Match Judge** later attaches a **Match Verdict** to the 5 winners. _Avoid_: output format, dict structure.
+
+**Raw Description**: The full body text of a **Position**, normalized to plain Unicode with `\n\n` paragraph breaks (no HTML, Markdown, or entities). Each parser owns normalization for its source. Empty after normalization is allowed (`raw_description = ""`). Input to the **Relevance Classifier** (where the **Structured Extract** is produced) and rendered verbatim into the **Card**'s `## Job Description`. The **Match Judge** never sees raw_description — it ranks on **Structured Extracts** only (ADR-0022). _Avoid_: description (when full text is meant); not to be confused with the **Match Verdict**'s `summary` or the **Structured Extract**.
+
+**Structured Extract**: A fixed-field representation of an in-domain **Position**, produced by the **Relevance Classifier** as side output alongside `in_domain: true`, consumed by the **Match Judge** as its sole per-candidate input. Carries `seniority`, `work_model`, `contract_type`, `key_skills: list[str]` (≤10), `key_responsibilities: list[str]` (≤10), `must_have_requirements: list[str]` (≤10), and free-text `notable_caveats: str` (≤200 chars) — the escape hatch for tone/negation ("kein Homeoffice"). Per ADR-0022. Persisted in `extracts.json` keyed by a **stable cross-URL identifier** (canonical-url or synthetic id, shared across tuple-aliased records per ADR-0003) so the same role's extract is paid once even when re-discovered under a syndicated URL. Classify worker writes eagerly (same fsync as `mark_in_domain`). Deleted on transition to `selected_by_judge` or `out_of_domain`. _Avoid_: summary (overloaded with **Match Verdict**'s `summary` — the classifier produces the extract, the judge produces the summary; these are different artifacts), classification (the verdict is the bool, the extract is its side output).
+
+### Filtering & scoring
+
+**Triage Profile**: The applicant's self-description plus rules deciding in-domain / good-match. Lives in `<settings-dir>/user-info/` as four markdown files — `self-description.md` (fed into both LLM call sites), `domain-fit.md` (classifier), `match-criteria.md` (judge), and `writing-style.md` (PRD-#16-v2.1 authoring skills only, NOT injected into v1 prompts). Per ADR-0016, the **Prompt Loader** concatenates the three v1-consumed files per call site; the **LLM Extractor** injects the payload into the hardcoded prompt's `{USER_INFO}` slot wrapped in `<user-info>` tags. Bullets/keywords, German, "extremely concise, sacrifice grammar for concision" (ADR-0026). Reused as v2 authoring context — no separate CV Profile. _Avoid_: profile (without qualifier), bio, CV Profile (retired before being built — do not reintroduce).
+
+**Skill**: A hard-skill or technology item from the **Config**'s `SKILLS`. Rendered as a bullet list into the **Match Judge** prompt's `{skills}` slot at `ClaudeExtractor` construction. Per ADR-0019, `SKILLS` is **only** consumed by the judge prompt — the **Domain Pre-Filter** no longer reads it. The LLM's `matched`/`missing` lists are open-vocabulary. _Avoid_: keyword (when matching).
+
+**Keyword**: A search term used to query a **Source**, from `Config.KEYWORDS`. Distinct from a **Skill** (does not affect judgment) and from `NEGATIVE_KEYWORDS` (which drives the **Domain Pre-Filter**). _Avoid_: skill (when querying), negative keyword (when querying).
+
+**Negative Keyword**: An entry in `Config.NEGATIVE_KEYWORDS`. Patterns (length ≥ 3) that, if found via case-insensitive substring match in a **Position**'s **title** (body text not consulted, per ADR-0019), cause the **Domain Pre-Filter** to drop the listing. No rescue mechanism. _Avoid_: blacklist, exclusion.
+
+**Match Verdict**: The structured output of the **Match Judge** for each of the 5 winners — `{rank: 1..5, matched: list[str], missing: list[str], summary: "2-3 sentences"}`. Open-vocabulary lists (validation is type/length only). `rank` is the explicit position in the **Daily Top-5** (1 = best). Drives **Card** content; **Match Tier** is retired (ADR-0020). _Avoid_: score, rating, tier (retired).
+
+**Rank**: The `rank` field — integer 1..5 assigned by the judge when picking the **Daily Top-5**. Surfaced in the **Card** via `{rank}` placeholder. Not a score (no cross-day comparability); not a tier (no enum). _Avoid_: tier (retired), score, position (overloaded).
+
+**Pool**: The implicit set of in-domain **Positions** eligible for today's **Match Judge** call — every URL in `.seen.json` with `status == in_domain` re-discovered by a parser in the current run. No separate data structure; computed per-run as `{url ∈ enriched_today : .seen.json[url].status == in_domain}`. Enter: classified `in_domain` (status flips, extract written). Exit: judge picks it (status → `selected_by_judge`, extract deleted) or no longer re-discovered (record sticks but never re-enters). No pool size cap, no TTL eviction in v1 (ADR-0022). _Avoid_: queue, candidate set, judge list — and not to be confused with **Daily Top-5** (the pool is the input set; the top-5 is the selected output).
+
+**Daily Top-5**: The 5 **Positions** the **Match Judge** returns from its single end-of-run call, drawn from today's **Pool**. ≤5 if pool was smaller. Surfaced as **Cards** in **Rank** order. Each winner gets `mark_selected_by_judge(stub)` after its **Card** is appended+fsynced, removing it from the **Pool**. _Avoid_: top-N, shortlist.
+
+**Relevance Classifier**: The call site that decides whether a **Position** is in the applicant's professional domain (AI / Data / Game Dev / SWE) and, when in-domain, produces its **Structured Extract**. Implemented as `LLMExtractor.classify_relevance_batch` — no wrapper class. Per-batch response: `[{"id": "...", "in_domain": true, "extract": {...}}, ...]` for in-domain, `[{"id": "...", "in_domain": false}, ...]` otherwise. Batched (default 100/call, ADR-0014); may stay pipelined with parsers or run serially. On `ClaudeUsageLimitError` the orchestrator sleeps until reset+2min (ADR-0023) and retries. Malformed batch (bad JSON, length/id mismatch) fails the whole batch — none marked seen; failure to `llm_classify_relevance.events.jsonl` and the full prompt+response to `llm_classify_relevance.transcripts.jsonl`. Per ADR-0018, every component identifier carries a layer prefix (`parser_`, `llm_`, `pipeline_`). Runs only on Positions that survive the **Domain Pre-Filter** and **Freshness Gate** with status `not_classified`. Off-domain Positions get `mark_out_of_domain(stub)` immediately. _Avoid_: filter (ambiguous — see **Domain Pre-Filter**), gate.
+
+**Freshness Gate**: A gate after `Parser.enrich()` and before the **Relevance Classifier**, dropping temporally invalid **Positions** (ADR-0025). Owns its full operational protocol — verdict, per-Position transcript, per-reason counter, drop cleanup, per-run aggregate — behind `admit(position) -> bool` / `emit_run_complete()`. Drop conditions: `posted_date is not None and (anchored_today - posted_date).days > MAX_LISTING_AGE_DAYS`, **or** `deadline is not None and deadline < anchored_today`. `None` on a field is "no signal, don't drop on that field alone"; both `None` → pass. `anchored_today` is the cron-anchored logical date (ADR-0021), shared with the **Daily Results File**. Drops write status `expired`; on `in_domain → expired` the URL's `extracts.json` entry is deleted. Runs on **every** enrich including Pool re-discovery, so pool items naturally age out. Log component `pipeline_freshness`. Future-dated `posted_date` (negative age) passes silently. _Avoid_: staleness filter, expiry gate, date filter.
+
+**Domain Pre-Filter**: A gate before the **Relevance Classifier**, dropping **Positions** whose **title** matches any **Negative Keyword** (title-only, blacklist-only, no whitelist — ADR-0019). Substring match, case-insensitive after `normalize()`. Owns its full operational protocol behind `admit(position) -> bool` / `emit_run_complete()`. Drops write status `out_of_domain` (same status the classifier writes for LLM-rejected items, per ADR-0020 renaming). Enumerates all matching keywords internally so it records per-position decisions to `pipeline_prefilter.transcripts.jsonl` and emits a per-keyword end-of-run summary to `pipeline_prefilter.events.jsonl`. Transcript record: `url, title, source, passes, reason ∈ {passed, blacklist_drop}, blacklist_matches, title_len`. Aggregate counts *positions matched* (not raw occurrences) and surfaces a `NEGATIVE_KEYWORDS_dead` list of zero-match keywords. Assumes input has been keyword-filtered upstream (parser invariant). _Avoid_: filter (ambiguous — see **Relevance Classifier**), gate, classifier.
+
+**Match Judge**: The call site that picks the **Daily Top-5** from today's **Pool**. Implemented as a single `LLMExtractor.judge_top_n(candidates)` per run — no wrapper class, no per-item call. Per ADR-0020, takes `list[JudgeCandidate]` (stable id + **Structured Extract**) and returns up to 5 **Match Verdicts** (`{id, rank, matched, missing, summary}`). The judge sees only structured extracts — no `raw_description` in the judge prompt. **Skills** and the **Triage Profile**'s match-criteria reach the judge via `{skills}` and `{USER_INFO}` slots. On `ClaudeUsageLimitError` orchestrator sleeps and retries (ADR-0023). On any non-quota error the run fails without writing a daily file, and a **Failure Report** is emitted. Runs only on days the **Pool** is non-empty.
+
+### Deduplication and run state
+
+**Deduplication**: Skipping **Positions** seen in a previous run or earlier in the current run. Three-tier: an in-run ephemeral URL set (`RunScopedDedup`, obtained from the **Deduplication Store** via `run_scope()` context manager, sits in front of the persistent store to absorb the Cartesian overlap without paying duplicate `enrich()` cost) plus the persistent **Deduplication Store** with two tiers: exact-match on URL, plus exact-match on `(company_lc, title_lc, location_lc)`. The tuple tier fires only when **all three fields are non-`None`** on both sides. When the tuple matches under a new URL (syndicated copy), the store records an alias under the new URL — copying `status` and `first_seen` — so subsequent runs hit the cheap URL tier (ADR-0003). `first_seen` answers "when did this *role* first appear", not "when did this URL first appear". `is_seen` returns a `SeenResult`: `url_hit`/`tuple_hit` skip; `in_domain` enriches and routes directly into the **Pool** for today's judge call (no classify pass); `miss` processes from scratch. Alias write is performed inside `is_seen`.
+
+**Dedup status enum** (per ADR-0020 / ADR-0022, supersedes the prior set):
+- `not_classified` — first-contact write; eligible for the classifier next re-discovery.
+- `out_of_domain` — written by **Domain Pre-Filter** (title hit) and **Relevance Classifier** (LLM `in_domain: false`). Terminal-skip.
+- `in_domain` — written by classifier on `in_domain: true`, alongside the **Structured Extract** in `extracts.json`. Means "in the **Pool**"; re-discovery routes directly into today's judge candidates.
+- `selected_by_judge` — written after judge picks the item and the **Card** is appended+fsynced. Terminal-skip; extract deleted.
+- `expired` — written by **Freshness Gate** when `posted_date` exceeds `MAX_LISTING_AGE_DAYS` or `deadline` < anchored date (ADR-0025). Terminal-skip. May transition from `not_classified` or `in_domain` (the latter also deletes the extract).
+- `enrich_failed` — parser's `enrich()` raised `ParserError` (incl. per-URL 4xx wrapped by HTTP layer). Terminal-skip.
+- `external_redirect` — parser emitted `ExternalRedirect` (ADR-0013). Terminal-skip.
+
+**Error semantics for `mark_*`** (orchestrator behavior, single-writer Pi):
+- **Pre-filter drop** → `mark_out_of_domain(stub)` immediately. No LLM cost.
+- **Classifier non-quota error**: batch fails; items NOT marked; orchestrator continues with other batches and still calls the judge on what classified successfully (ADR-0021). Next run retries.
+- **Classifier `ClaudeUsageLimitError`** (ADR-0023): parse reset time, sleep until reset+2min (or fallback `next_top_of_hour + 2min`), retry the batch. No `degraded_reason`; no Failure Report. Cron-anchored day (ADR-0021) handles midnight crossings.
+- **Judge non-quota error**: no daily file; **Failure Report** emitted; **Pool** intact (no `selected_by_judge` transitions); tomorrow sees today's pool plus tomorrow's arrivals.
+- **Judge `ClaudeUsageLimitError`**: sleep and retry.
+- **Per-card append succeeds, then judge processing fails mid-loop**: each card is appended+fsynced+`mark_selected_by_judge` atomically per winner. A failure between cards leaves earlier winners marked, later winners unmarked (back in pool for tomorrow) — bounded.
+- **`enrich()` raises `ParserError`** → `mark_enrich_failed(stub)`. Terminal-skip. Includes per-URL 4xx from `ParserHttp.get()` (404/400/422 wrapped by HTTP layer; auth/5xx raise `HttpParserFatalError` and propagate to thread-bootstrap, becoming `PARSER_DEAD`).
+
+State lives in `.seen.json` (synced via Syncthing alongside Daily Results Files, ADR-0002), shaped `{url: {company_lc, title_lc, location_lc, status, first_seen}}` (any of the lowercased fields may be `None`); fuzzy index built in-memory at load, not persisted. `DeduplicationStore` exposes seven narrow methods (one per status: `mark_out_of_domain`, `mark_in_domain` — takes the extract as kwarg, `mark_selected_by_judge`, `mark_expired`, `mark_enrich_failed`, `mark_external_redirect`, `mark_not_classified`). Pipeline is single-writer at the process level (ADR-0002); the lock inside `DeduplicationStore` (ADR-0014) covers concurrent classify/judge worker writes. Parser threads remain pure producers. **Migration**: ADR-0024 wipes the previous `.seen.json` and the old trio; no automatic translation. _Avoid_: duplicate filtering, URL filtering.
+
+### Display
+
+**Card**: The expanded view rendered for **every** **Daily Top-5** winner. Structure: H1 `# {company} · {title} · {location_segment}` (`location_segment` = literal `location` for on-site/location-only; `{location} (Hybrid)`/`(Remote)` when a non-on-site `work_model` is known; `Unknown Location` when `location` is `None`; `Unknown Location (Hybrid|Remote)` for `None`-location + non-on-site). Below H1: meta line `posted_date · contract_type · employment_type` (None segments omitted; whole line omitted if all None); `**Salary:** {salary}` (omitted on `None`); `## AI Assessment` opening with `**Rank {rank}/5**`, then summary, then `**Matched:**`/`**Missing:**` bulleted lists (each list+label omitted when empty); `## Job Description` (whole section omitted on empty `raw_description`); horizontal rule and bare-autolink URL footer. Headings are English.
+
+**Renderer**: A pure module exposing `render(position, verdict, layout) -> str`. Uses the **Layout**'s `CARD_TEMPLATE`. Builds a placeholder dict + named groups + `rank`, substitutes via `str.format_map`, returns the block. No file I/O, deterministic. No tier-derived placeholders (ADR-0020). _Avoid_: formatter, presenter.
+
+**Results File Manager**: The only module that reads or writes the **Daily Results File**. Function-shaped: orchestrator holds the day's `Path` (`<settings-dir>/results/{cron_anchored_date}.md`, ADR-0021) and dispatches. Surface: `ensure_initialized(path)` (`mkdir(parents=True)`; no header — files start empty), `append(path, rendered_block)` (verbatim write + `flush` + `os.fsync`, propagates `OSError`). `data_dir` is the parent of the loaded `config.py` (ADR-0011). _Avoid_: writer, output manager.
+
+### Observability
+
+**Log Artifacts**: Files under `logs/`, laid out **by reader** (ADR-0018). Four types: `<comp>.events.jsonl` (one structured row per step; the run-end metrics row that used to live on the retired Run Divider now lands as `event=run_complete` here per ADR-0021); `lifecycle.jsonl` (single shared file carrying status-display `registered`/`phase_changed`/`removed` events); `run.log` (single shared file carrying tracebacks and `SUMMARY OF SESSION` blocks); `<comp>.transcripts.jsonl` (LLM components only — full prompt/response payloads). Every component identifier carries a layer prefix — `parser_`, `llm_`, `pipeline_`. For LLM code, **component is the call site** (`llm_classify_relevance`, `llm_judge_match`), not the implementation class. _Avoid_: log file (without qualifier), debug log.
+
+**Run Log**: The per-run instance that writes the **Log Artifacts** to `logs/`. Constructed once at orchestrator entry from `cfg.logs_dir`; threaded as a kwarg into every component that emits log events (`RunMetrics`, `ClaudeExtractor`, the status-display core, the outbound dispatcher, every **Parser** via context-manager construction which forwards into its `ParserHttp`). Owns the directory path, file-naming convention, JSONL envelope shape, and `=== <component>  <ts>  <kind> ===` header convention in `run.log`. Filesystem errors propagate as `OSError`. Safe to share across threads — each method opens, writes, closes per call. _Avoid_: log writer, logger (overloaded with `logging.Logger`).
+
+**Status Display**: A live, in-process view of pipeline progress. Ephemeral — exists only while `run()` executes. A `StatusDisplay` Protocol with two implementations: `RichStatusDisplay` (`rich.Live` table repainting at ~4 Hz, when `sys.stdout.isatty()`) and `PlainStatusDisplay` (line-by-line `print`, Pi cron). One row per stage: overall `pipeline` phase, transient `startup`, one **Agent Row** per configured **Parser** (`parser_<parser_type>`), and rows for `pipeline_dedup`, `pipeline_prefilter`, `pipeline_freshness`, `llm_classify_relevance`, `llm_judge_match`. Body strings formatted by **RunMetrics**. `register()`/`update_phase()` also emit to `lifecycle.jsonl` (ADR-0018). _Avoid_: progress bar (implies known total), TUI, dashboard.
+
+### Sources & extraction
+
+**Source**: A configured job board or API in `Config.SOURCES`, declared as a `SourceEntry` carrying a **Parser Type** and per-source `max_results`. A **Source** is a *config entry* (what to search); a **Parser** is the *module* (how). One-to-one in v1. _Avoid_: site, board.
+
+**Parser**: A Python module in `src/application_pipeline/parsers/`. Two-phase API: `discover(query)` returns cheap **Position Stubs**; `enrich(stub)` fetches the detail page and returns a full **Position**. The orchestrator runs **Deduplication** between phases. Each parser is a context manager owning a single `httpx.Client`; no shared mutable module-level state (ADR-0005). The orchestrator owns Cartesian expansion of `KEYWORDS × LOCATIONS [+ remote]` and emits one `discover(ParserQuery(keyword, location, max_results))` per combination; `location` is sealed **Location** (`City(name) | Remote`). Each parser declares its **Location Coverage** as module-level symbols (ADR-0012). Parsers own all per-host pacing; the orchestrator never sleeps between queries. Parsers may emit `ExternalRedirect` from `enrich`. **Keyword-match invariant** (ADR-0019): every stub yielded from `discover()` is expected to match its `ParserQuery.keyword` in the title. _Avoid_: scraper, fetcher.
+
+**Position Stub**: The cheap result of `Parser.discover()` — `url, title, company, location, source`. Required: `url, title, source`. Optional (`str | None`): `company, location`. _Avoid_: preview, summary.
+
+**External Redirect**: A payload emitted by a **Parser**'s `enrich()` instead of a `Position` when the detail page carries an outbound URL **and no usable body**. Carries `PositionStub` + `outbound_url`. Orchestrator marks the stub `external_redirect` and bumps the `external_redirects` counter. A separate `external_redirect` event with `skipped=false` may also be emitted by a parser that detected an outbound URL but still produced a normal `Position` — for outbound-host analysis, does not affect dedup state or the skip counter (ADR-0013). _Avoid_: redirect stub, forwarded listing.
+
+**Parser Type**: The string on a `SourceEntry` identifying which **Parser** to use — maps directly to a filename in `parsers/`. _Avoid_: adapter.
+
+**Location**: Geographic slot the orchestrator passes via `ParserQuery.location`. Sealed sum type: `City(name: str)` for a named place from `Config.LOCATIONS`, `Remote` for the remote-only slot when `INCLUDE_REMOTE=True`. _Avoid_: place, geo.
+
+**City**: The `City(name)` arm. `name` is the user-typed string, normalized via `normalize()` before lookup. No central catalog — resolvable city names are the dynamic union of configured **Sources**' `serves()` predicates. _Avoid_: town, place.
+
+**Remote**: The `Remote` arm. Each **Parser** decides what `Remote` means for its **Source** via `remote_wire()`. _Avoid_: homeoffice, work-from-home (when the type variant is meant).
+
+**Location Coverage**: The module-level **Protocol** every **Parser** satisfies — `serves(name: str) -> bool`, `to_wire(name: str) -> str`, `serves_remote: bool`, `remote_wire() -> Any`. Each parser is local authority. **Config Loader** validates `LOCATIONS` at load time and rejects unresolvable entries with `ConfigError`. Per ADR-0012. _Avoid_: location map, slug table.
+
+**LLM Extractor**: A Protocol with two methods — `classify_relevance_batch(items: list[ClassifyItem]) -> (list[RelevanceVerdict], CallUsage)` and `judge_top_n(candidates: list[JudgeCandidate]) -> (list[MatchVerdict], CallUsage)`. `ClassifyItem` carries opaque `id`, `title`, `raw_description`; response is id-keyed (`[{"id":..., "in_domain": bool, "extract": {...} | absent}, ...]`). `RelevanceVerdict` is `{in_domain, extract: StructuredExtract | None}` (extract non-None iff in-domain). `JudgeCandidate` carries stable id, **Structured Extract**, and the `Position`'s `stub` fields for tie-breaking. Hardcoded prompts live in `src/application_pipeline/templates/prompts/`; **Triage Profile** injected via `{USER_INFO}` slot; **Skills** bound at construction. The v1 production implementation is `ClaudeExtractor` shelling out to **Claude Code CLI** (`claude -p - --output-format json --model <alias>` + `--effort <level>` where applicable) as a fresh subprocess per call. Per ADR-0015: `haiku` (no `--effort`) for the classifier, `haiku` with `--effort medium` for the judge. Structured outputs wrapped in `<verdicts>` tags and parsed via **Agent Output Protocol** (ADR-0015). On `ClaudeUsageLimitError` the implementation parses the 429 reset time and raises `ClaudeUsageLimitError(reset_time)` so the orchestrator can sleep (ADR-0023). _Avoid_: LLM, model (without qualifier).
+
+**Agent Output Protocol**: A project-agnostic pure module under `application_pipeline/llm/` that extracts a structured JSON payload from a CLI response whose `result` carries free-form text with payload wrapped in a semantic XML tag (ADR-0015). Exposes `extract_json_block(text: str, tag: str) -> Any` + `AgentOutputProtocolError(kind: "tag_missing" | "json_malformed")`. Finds rightmost `</tag>`, walks back through preceding `<tag>` openings, strips an optional surrounding markdown fence, then `json.loads`. Returns the first candidate that parses; raises on no tag / no parse. The **LLM Extractor** catches at its call-site boundary and re-raises as `ExtractorBatchMalformedError`/`ExtractorMalformedJSONError`. _Avoid_: output parser (too generic), response handler (overloaded with HTTP).
+
+**Pagination**: Successive page fetches per **Source**, preferably ordered newest-first by `posted_date`, until either the source signals no next page **or** the per-Source `max_results` cap is reached. Per ADR-0017 there is no dedup-driven discover early-stop. `SKIP_AND_END_QUERY` (ADR-0007) is only emitted on `run_state.is_aborted`. Each `SourceEntry` carries its own cap (default 1000).
+
+### Invocation
+
+The package is distributed via PyPI (ADR-0027). Hosts install into a project-local `.venv` (`python3 -m venv .venv && .venv/bin/pip install application-pipeline`), bootstrap the settings folder with `application-pipeline init <dir>`, and arm cron with `bash <dir>/setup/cron-install.sh`. Cron fires **once per day at 00:30 local** (ADR-0024). Each tick runs the seeded `setup/cron.sh`: `pip install --upgrade application-pipeline` (×2 for CDN propagation), `application-pipeline init --refresh <dir>` (self-heal new template files), then `application-pipeline run <dir>/config.py`. A global `flock` at `$APPLICATION_PIPELINE_HOME/.cron.lock` (modelled on pycastle's pattern) serialises overlapping ticks; a run that sleeps through a quota window (ADR-0023) may overlap the next cron fire, which the flock silently waits out — absence of the next day's daily file is the operator signal. The laptop is used only during development to smoke-test individual **Parsers** in isolation. Note: `pycastle/` in this repo is an unrelated RALPH Loop coding-agent plugin used to *build* this project; its quota-handling logic (`pycastle/services/claude_service.py:88-145`) is the reference port for ADR-0023's parse-and-sleep behavior, and its `setup/*.sh` scripts are the reference shape for ADR-0027's seeded cron wrappers.
+
+## Relationships
+
+- A **Position** is written into a **Daily Results File** only if it passes the **Domain Pre-Filter**, then the **Freshness Gate**, then the **Relevance Classifier** (status → `in_domain`), then is picked into the **Daily Top-5** by the **Match Judge** (status → `selected_by_judge`). The **Freshness Gate** also re-runs on Pool re-discovery, so pool items can transition `in_domain → expired` before today's judge call.
+- The **Pool** is the set of `status == in_domain` URLs re-discovered by a parser in the current run — an emergent property of `.seen.json` + today's parse output, not a stored data structure.
+- The **Match Judge** runs once per run on the **Pool**, takes **Structured Extracts** plus construction-bound **Skills** and the injected **Triage Profile**, returns up to 5 **Match Verdicts** with explicit **Rank**.
+- The **Triage Profile** reaches the LLM via the hardcoded prompt's `{USER_INFO}` slot (ADR-0016); **Skills** are bound at `ClaudeExtractor` construction and reach the LLM via `{skills}`; `NEGATIVE_KEYWORDS` reaches the **Domain Pre-Filter** directly (ADR-0019).

application_pipeline-0.6.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: application-pipeline
+Version: 0.6.0
+Requires-Python: >=3.11.3
+Requires-Dist: beautifulsoup4
+Requires-Dist: httpx~=0.27
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Requires-Dist: ruff; extra == "dev"

application_pipeline-0.6.0/README.md

@@ -0,0 +1,48 @@
+# application-pipeline
+
+A personal job-discovery and triage pipeline. It fetches listings from configured sources, filters
+out noise, classifies each position's relevance with Claude, accumulates a rolling pool of in-domain
+candidates, and emits one dated results file per day ranking the top five matches.
+
+## Why
+
+- **Automated discovery** — parsers walk configured job boards each morning so you don't have to.
+- **Noise reduction** — the Domain Pre-Filter drops title-level mismatches cheaply, before any LLM
+  cost is incurred.
+- **Freshness control** — the Freshness Gate discards listings beyond your configured age ceiling and
+  any past their deadline.
+- **Structured ranking** — the Match Judge scores each in-domain candidate against your skills and
+  match criteria, returning an explicit rank with matched/missing skill lists.
+- **One file per day** — a dated markdown file with up to five cards lands in your settings folder
+  and propagates via Syncthing if configured.
+
+## The pipeline
+
+Each cron tick walks every configured Source × Keyword × Location combination, then routes each
+Position through the following phases in order:
+
+1. **Parsers** — `discover()` yields cheap Position Stubs; `enrich()` fetches the detail page and
+   returns a full Position with raw description.
+2. **Deduplication** — skips URLs seen in previous runs (exact URL or company/title/location tuple),
+   routing known in-domain positions directly back into the Pool.
+3. **Domain Pre-Filter** — drops any Position whose title matches a Negative Keyword (configured in
+   `config.py` as `NEGATIVE_KEYWORDS`).
+4. **Freshness Gate** — drops listings older than `MAX_LISTING_AGE_DAYS` or past their deadline.
+5. **Relevance Classifier** — a batched Claude call decides `in_domain: true/false`; in-domain
+   positions receive a Structured Extract and enter the Pool.
+6. **Match Judge** — a single Claude call at end-of-run picks the Daily Top-5 from the Pool,
+   returning a Match Verdict (rank, matched skills, missing skills, summary) for each winner.
+7. **Daily Results File** — the five Cards are written to `<settings-dir>/results/YYYY-MM-DD.md` in
+   rank order.
+
+## Getting started
+
+- **[docs/usage.md](docs/usage.md)** — installation, CLI reference, and per-file editing guide for
+  the settings folder.
+- **[docs/cron-setup.md](docs/cron-setup.md)** — unattended operation via cron, flock semantics,
+  optional Syncthing, migration from a legacy layout, and PyPI release procedure.
+
+## Acknowledgements
+
+Install flow, cron wrapper shape, and flock-based serialisation modelled on
+[pycastle](https://github.com/Johannes-Kutsch/pycastle).

application_pipeline-0.6.0/docs/adr/0001-claude-cli-as-llm-backend.md

@@ -0,0 +1,17 @@
+# Claude Code CLI as the LLM backend
+
+**LLM Extractor** drives Claude via `claude -p --output-format json` headless subprocess from the Pi. Runs against the user's Claude Code subscription (auth via one-time `claude login`); Anthropic API off-limits as budget item.
+
+## Why
+
+- **Pi 5 can't sustain local inference cheaply.** Inference off-device makes the Pi a thin coordinator — HTTP out, markdown in. No thermal headroom, no model pulls, no `keep_alive` tuning.
+- **Headless mode works unattended.** `claude -p` is a normal subprocess driveable from cron; subscription auth in `~/.claude/` inherits via the user's home.
+- **Quality ceiling lifts.** Claude beats Qwen on German listings without prompt-engineering acrobatics.
+- **Subprocess + envelope, not SDK.** `--output-format json` returns envelope with `usage` (input/output/cache-read tokens), `total_cost_usd`, `session_id`. Anthropic SDK and Claude Agent SDK both wrap the same CLI but default to API keys — rejected.
+- **Subscription rate-limit handling is structural.** Usage-limit errors surface in the envelope. See ADR-0023 for the sleep-and-retry behaviour.
+
+## Consequences
+
+- `Config`: `claude_classify_batch_size: int` (default 100, see ADR-0014) and optional `claude_cli_path`.
+- Auth file `~/.claude/.credentials.json` lives outside `data/` deliberately — replicating OAuth through Syncthing is worse than a one-time re-auth.
+- Run-time cost shifts from electricity to subscription quota. Per-call-site Claude token/cost fields land in `pipeline_orchestrator.events.jsonl` (see ADR-0018).

application_pipeline-0.6.0/docs/adr/0002-seen-state-durable-via-syncthing.md

@@ -0,0 +1,18 @@
+# Deduplication state (`.seen.json`) is durable via Syncthing
+
+`.seen.json` lives at `data/.seen.json` (sibling to `data/results/`, per ADR-0011), inside the Syncthing-synced folder. The Pi is sole writer; the laptop's mirror is the backup. Not tracked in git.
+
+## Why
+
+- **Pipeline memory across resets.** The **Daily Results File** is per-day; if `.seen.json` reset too, every fresh day floods with listings the pipeline already showed.
+- **Backup without a credential on the Pi.** Syncthing was already the transport for results — adding `.seen.json` is free, and the laptop mirror is disaster recovery.
+- **History in the file, not the transport.** `first_seen` answers "when did I first see this URL"; git per-commit history was overkill.
+- **Single-writer, no conflict surface.** Only Pi writes. Laptop never runs the full pipeline. Sibling-to-results placement also survives a `mv data/results data/results.archive` reset gesture.
+
+## Consequences
+
+- `.gitignore`d.
+- Crontab wraps the entry point with `flock -n` so a still-running invocation causes the next cron tick to exit immediately.
+- Disaster recovery: copy laptop's Syncthing copy back into place.
+- Schema migrations: see ADR-0024 — the v2 cutover wipes the file instead.
+- If a future stage introduces a second writer, the single-writer assumption needs a locking/merge strategy.

application_pipeline-0.6.0/docs/adr/0003-dedup-alias-on-tuple-match.md

@@ -0,0 +1,17 @@
+# Tuple-match writes a URL alias inside `is_seen`
+
+When `is_seen` matches via the `(company_lc, title_lc, location_lc)` tuple under a *new* URL (syndicated copy), the **Deduplication Store** internally writes an alias entry under the new URL — duplicating the original record's `status` and `first_seen` — so subsequent runs short-circuit on the cheap URL lookup. The return value (the `SeenResult` variant) is unaffected; the alias is a transparent side effect of the read.
+
+## Why
+
+- **Most stubs expose URL before description.** Re-doing tuple normalisation + lookup on every run for an already-recognised syndicated copy is repeated work.
+- **Alias-write internal to dedup module.** A caller-driven `record_alias` would force every `is_seen` call site to remember a follow-up — a footgun. Folding the write into `is_seen` removes it.
+- **On-disk shape stays flat.** Each entry is self-describing `{url: record}`; no sum type on disk.
+- **`first_seen` semantics stay correct.** Alias copies the *original*'s `first_seen` — the paper trail answers "when did this *role* first appear".
+
+## Consequences
+
+- Single-writer Pi (ADR-0002) means a side-effecting query is safe.
+- `is_seen` may raise `OSError` from the alias write; the orchestrator's top-level `mark_*` handler covers it.
+- Future fuzzy-match upgrades on the `_tuple_lookup` seam inherit the alias-write automatically.
+- `is_seen`'s docstring must call out the side effect.

application_pipeline-0.6.0/docs/adr/0004-layout-as-user-editable-python-module.md

@@ -0,0 +1,20 @@
+# Layout as a user-editable Python module in the synced folder
+
+`settings/layout.py` lives alongside `config.py` in the synced folder (see ADR-0011). Plain Python: named placeholder groups, full `CARD_TEMPLATE` / `HEADLINE_TEMPLATE`. Loaded at runtime by the same `load_user_module` machinery as **Config**, validated into a frozen `Layout` dataclass, consumed by a pure **Renderer** via `str.format_map`.
+
+When `LAYOUT` is unset, the loader defaults to `"layout.py"` next to `config.py` and **errors if missing** — matching how `USER_INFO_DIR` resolves. An explicit `LAYOUT = None` selects the built-in `layout.default()` stub (reserved for tests).
+
+## Why
+
+- **User iterates on layout often, package code rarely.** Field tweaks, emoji swaps, visual hierarchy — should not require editing `src/`. Co-location with `config.py` matches the edit-restart-see workflow.
+- **`str.format_map` + Python constants is the lightest tool.** No Jinja, no DSL. Named placeholder groups (`PLACEHOLDER_GROUPS = {"meta": (" · ", ["location", "url"])}`) handle the dangling-separator problem.
+- **Loader plumbing already exists.** `load_user_module` (extracted from Config Loader) handles `importlib.util`, missing-attr checks, typed errors. `LayoutError` and `ConfigError` share `UserSettingsError`.
+- **Renderer stays pure.** Layout passed in explicitly (`render(position, verdict, layout)`); no module-level state.
+- **Auto-discovery footgun closure.** A user with a valid `layout.py` who forgot to add `LAYOUT = "layout.py"` would silently get the stub. Pattern-symmetry with `USER_INFO_DIR` + fail-loud on missing closes the gap. Explicit `LAYOUT = None` keeps the stub reachable.
+
+## Consequences
+
+- Renderer takes a `Layout` argument; orchestrator loads once at startup and threads it through.
+- `LayoutError` joins `ConfigError` under `UserSettingsError`.
+- Typo in placeholder name raises `KeyError` from `str.format_map` at render time — fail-loud is intentional.
+- Validation at startup: `layout_loader` checks every `placeholder_groups` entry references a known field; missing/invalid `layout.py` fails before the first fetch.