masterly 0.2.0__tar.gz → 0.5.0__tar.gz

masterly-0.5.0/.claude/PROJECT-CLAUDE.md

@@ -0,0 +1,138 @@
+# Agent guidance for Masterly (project-wide)
+
+This file is the **shared context for every Claude session in any Masterly repo**. Claude Code loads it automatically when working inside `/Users/clarsson/projects/masterly/` or any subdirectory.
+
+Per-repo `CLAUDE.md` files (in each repo root) add repo-specific guidance on top of this one. Architectural source of truth is `masterly-framework/docs/`.
+
+## What Masterly is
+
+Masterly is a modern Master Data Management (MDM) SaaS for organizations replacing Excel or no-tool today. Target customers run Databricks, Snowflake, or Microsoft Fabric. Masterly is an **active processing pipeline** (REST/Stream/MCP ingest → Identity Resolution → Golden Resolution → Data Quality → REST/Stream/MCP extract), not just a catalog or metadata layer.
+
+For the full picture: [`masterly-framework/docs/product/overview.md`](masterly-framework/docs/product/overview.md).
+
+## Hard architectural constraints
+
+These are non-negotiable. Every design must satisfy all of them:
+
+1. **Two-axis deployment factoring** — compute tier (`shared` | `dedicated` | `self-hosted`) × data tier (`masterly-db` | `byo-db`) yields 5 valid combinations. Self-hosted is the initial GTM. The legacy term "BYOC" is retired; use "BYO-DB" on the relevant compute tier. See [`masterly-framework/docs/architecture/deployment-models.md`](masterly-framework/docs/architecture/deployment-models.md) and [ADR 0002](masterly-framework/docs/adr/0002-deployment-topology.md).
+2. **Region pinning per Environment** — EU and US at minimum. No cross-region data leakage in logs, telemetry, or backups.
+3. **DBU instrumentation on every tier; billing only on usage tiers** — every meaningful operation emits a DBU event to the Environment's local `dbu_events` ledger, on all five combinations. `billing_mode` never gates emission ([ADR 0034](masterly-framework/docs/adr/0034-dbu-event-taxonomy-weights-and-usage-reporting.md)). What is gated is *export and invoicing*: only `billing_mode == "usage"` (Shared MT, Dedicated) ships aggregates to Masterly's metering store, via the telemetry receiver. Self-hosted is fixed-price — local usage visibility, no billing pipeline.
+4. **Stateless services** — no in-memory session state. Postgres for durable data-plane state, Cosmos NoSQL for control-plane state, Redis for cache/ephemeral.
+5. **Local-LLM support** — self-hosted and BYO-DB customers will not ship master data to OpenAI/Anthropic. The AI Router/Gateway abstracts the LLM.
+6. **Configuration is managed, not ad-hoc** — customer config (data models, rules, mappings) is versioned, JSON-Schema-validated, and promotable across Environments. Two modes per Environment ([ADR 0026](masterly-framework/docs/adr/0026-config-management-modes.md)): **Managed (Click-Ops, default)** — stored and versioned in the product — or **GitOps** — config-as-code in the customer's repo. GitOps is optional.
+7. **Data never lives in configuration** — master data, golden records, and IR decisions stay in Postgres, never in Git or a config snapshot.
+
+## Canonical hierarchy and terminology
+
+```
+Organization (paying account, = Stytch Organization)
+└── Environment (e.g. prd-eu, prd-us, non-prd-eu — region pinning lives here)
+    └── Workspace
+        └── Domain
+            └── Data Model
+                └── Data Product
+```
+
+**Use "Environment," not "Tenant."** Earlier brand materials used "Tenant" for what is now called Environment; that term is deprecated.
+
+**Unit of data isolation = Environment.** The data plane is provisioned per-Environment (DB-per-Environment), not per-Organization.
+
+**Deployment grouping = Install** ([ADR 0039](masterly-framework/docs/adr/0039-installs-as-environment-deployment-grouping.md)). An **Install** is one deployment of the stack (one compute unit + control plane, one `terraform apply`) that hosts a set of an Org's Environments: `Organization 1—N Install 1—N Environment`. It is a **deployment-axis** concept, **not** a level in the logical hierarchy above — navigation stays Organization → Environment → Workspace, and the user's Environment switcher is Org-scoped and Install-invisible. It is what lets a customer separate *infrastructure* (e.g. prod vs non-prod in different subscriptions, on different versions). First-class on the `self-hosted` and `dedicated` tiers; degenerate on `shared`.
+
+## Repo map
+
+All repos live under `github.com/masterly-data/`. Local clones expected under `/Users/clarsson/projects/masterly/`.
+
+| Repo | Purpose | Layer(s) |
+|---|---|---|
+| `masterly-framework` | **Architectural source of truth** — ADRs, architecture docs, design system, this CLAUDE.md, conventions | All — shared |
+| `masterly-platform-iac` | Terraform for Masterly's platform infrastructure | Layers 1 (shared) + 2 (regional CP) |
+| `masterly-shared-iac` | Terraform for Shared MT data plane | Layer 3 (placeholder until first Shared MT customer) |
+| `masterly-dedicated-iac` | Terraform for per-customer Dedicated cells | Layer 4 (placeholder until first Dedicated customer) |
+| `terraform-azurerm-masterly` | **Public** (Apache 2.0) Terraform module customers and partners consume at a semver tag. No credential to fetch — the gate is images + licence ([ADR 0067 amendment 2026-09-01](masterly-framework/docs/adr/0067-customer-artifact-distribution.md)). | Layer 5 — the shipped module |
+| `masterly-demo-iac` | Private: **Masterly's own demo install only** (`deployments/demo-eu`) plus the workflows that plan/apply/operate it. Renamed from `masterly-self-hosted-iac` on 2026-09-07, when the module copy at its root was deleted (MAS-42) — **the module lives in `terraform-azurerm-masterly` and nowhere else.** Not what customers consume. | Layer 5 — internal |
+| `masterly-platform-backend` | FastAPI control-plane services: `license-issuer`, future `tenant-router` + `billing-aggregator`. Masterly-operated; never ships to customers. | Layer 2 (regional CP) |
+| `masterly-application-backend` | FastAPI product application: `api`, `workers`, future `ai-router`, plus business modules (IR, golden, DQ). One codebase across all deployment models. | All — application code (data plane) |
+| `masterly-application-frontend` | Next.js + Stytch B2B user sessions. Ships with the application backend across all deployment models. | All — application code |
+| `masterly-python-sdk` | **Public** (Apache-2.0) **Python client** (`pip install masterly`, v0.2.0 on PyPI) — extract (products/changes/golden) + ingest + configuration (workspaces/domains/data-models/sources) over `/v1` (ADR 0068), plus `examples/demo_data.py` for demo master data. Development history through v0.2.0 lives in the private `masterly-python-sdk-archive`. | Customer-side tooling |
+| `masterly-web` | **Public web** — marketing site (`masterlydata.com`) + customer docs (`/docs`). Astro + Starlight, static, on Azure Static Web Apps. Masterly-operated; ships to no customer; shares only design tokens with the frontend. See [ADR 0030](masterly-framework/docs/adr/0030-public-web-marketing-and-docs.md). | Public web (marketing + docs) |
+| `masterly-demo01-cac` | GitOps config-as-code for the demo install: Data Models, IR rules, `modules.yaml`. (Named `demo-config` in older docs and in ADRs 0012/0014 — those record history; this is the live name.) | Layer 5 — demo install |
+
+The demo install (subscription `msly-demo-01-eu`) lives in `masterly-demo-iac/deployments/demo-eu/` and consumes the **published** module at a pinned version (`source = "masterly-data/masterly/azurerm"`), exactly as a customer does. It used to consume it by local path, which dogfooded every module change against the live demo for free; that no longer happens, so **plan a live install against the module branch before tagging a module release** (decided 2026-06-11; changed 2026-08-31 when the module was published).
+
+## Tech stack
+
+- **Backend:** Python + FastAPI, stateless containerized microservices, sync + async patterns
+- **Frontend:** TypeScript + Next.js
+- **Data plane:** PostgreSQL + Redis (per-Environment)
+- **Control plane:** Cosmos DB NoSQL with multi-region writes (see [ADR 0016](masterly-framework/docs/adr/0016-cosmos-db-for-layer-2.md))
+- **Hosting:** Azure Container Apps
+- **Auth:** Stytch B2B (multi-org, multi-connection per org)
+- **IaC:** Terraform throughout, OIDC to Azure (see [ADR 0015](masterly-framework/docs/adr/0015-terraform-as-iac.md), [ADR 0017](masterly-framework/docs/adr/0017-github-actions-terraform-cd.md))
+- **CD:** GitHub Actions with OIDC federation, plan-on-PR + apply-on-merge with Environment approval
+
+API-first. The REST API contract is the primary interface. MCP, Stream, REST, and GUI are equally first-class channels.
+
+## Design system
+
+The Masterly design system lives in [`masterly-framework/design-system/`](masterly-framework/design-system/). When working on any UI surface (Next.js frontend, marketing pages, decks, prototypes):
+
+- **Tokens:** [`masterly-framework/design-system/colors_and_type.css`](masterly-framework/design-system/colors_and_type.css) is the single source of truth. Never hard-code colors, type sizes, or spacing.
+- **Brand fundamentals:** [`masterly-framework/design-system/README.md`](masterly-framework/design-system/README.md) — dark-first, warm-gradient, sharp-typographic. The signature `.` after "Masterly." is non-negotiable.
+- **Component reference:** [`masterly-framework/design-system/ui_kits/product/`](masterly-framework/design-system/ui_kits/product/) shows the product surface conventions.
+- **No emoji** in Masterly materials. Use Phosphor / Lucide / Heroicons outline sets.
+- **Magenta is sparingly used** — 60% dark, 30% gradient, 10% magenta accent.
+- **Sentence case** for all UI labels, buttons, and headings except the wordmark "Masterly.".
+
+## Decision-making protocol
+
+| Decision type | Where it lands |
+|---|---|
+| **New cross-cutting architectural decision** (affects multiple repos, hard to reverse) | New ADR in [`masterly-framework/docs/adr/`](masterly-framework/docs/adr/) using [`template.md`](masterly-framework/docs/adr/template.md). Mark Proposed; the user accepts it — and an acceptance is not complete until a card has carried that status into the ADR and its index row on `origin/main`, opened in the same pass the acceptance is recorded ([lifecycle](masterly-framework/docs/operating-model/lifecycle.md)). |
+| **Open question** that doesn't yet have a decision | New or updated file in [`masterly-framework/docs/architecture/open-questions/`](masterly-framework/docs/architecture/open-questions/) |
+| **Cross-cutting convention** (naming, error handling, file layout patterns) | New or updated file in [`masterly-framework/docs/conventions/`](masterly-framework/docs/conventions/) |
+| **Architecture detail** (how a subsystem actually works) | New or updated file in [`masterly-framework/docs/architecture/`](masterly-framework/docs/architecture/) |
+| **Repo-local convention** (file structure inside one repo, build patterns specific to that repo) | That repo's `CLAUDE.md` or `README.md` — not the framework |
+| **Operational runbook** | That repo's `RUNBOOK.md` or similar — not the framework |
+
+**Rule of thumb:** if a decision affects how a second engineer would build a feature in a *different* repo, it belongs in `masterly-framework`. If it affects how to wire one feature together in *this* repo, it stays local.
+
+## Naming conventions (cross-repo)
+
+| Surface | Pattern | Example |
+|---|---|---|
+| Domain (primary) | `masterlydata.com` | |
+| Subdomains | `<purpose>.masterlydata.com` | `cp.masterlydata.com`, `app.masterlydata.com`, `api.masterlydata.com` |
+| Azure subscriptions | `msly-<layer>-<env>-<geo>[-<slug>]` | `msly-shared-prod`, `msly-cp-prod-eu`, `msly-demo-eu` |
+| Azure resource groups (Masterly subs) | `rg-msly-<layer>-<purpose>-<cell>` | `rg-msly-shared-security` (shared = no cell), `rg-msly-cp-aca-eu01` |
+| Azure resource groups (customer self-hosted) | `rg-masterly-<install>-<purpose>` ([ADR 0039](masterly-framework/docs/adr/0039-installs-as-environment-deployment-grouping.md)) | `rg-masterly-prod-aca`, `rg-masterly-nonprod-data` |
+| ACA Environments | `aca-<layer>-<cell>[-<slug>]` | `aca-cp-eu01`, `aca-demo-eu01` |
+| Container Apps | `ca-<app-name>` | `ca-license-issuer`, `ca-frontend`, `ca-api`, `ca-workers` |
+| Cosmos DB (control plane) | `masterly-cp-cosmos-<cell>` | `masterly-cp-cosmos-eu01` (serverless, single-region per cell in v1 — ADR 0016) |
+| Container Registry | `masterly.azurecr.io` (single registry, geo-replicated) | |
+
+**Geo vs cell vs region** (per [ADR 0022](masterly-framework/docs/adr/0022-cell-based-resource-naming.md)):
+- **Geo** (`eu`, `us`) — the data-residency boundary. Lives in the **subscription / Environment** name (`msly-cp-prod-eu`, Environment `prd-eu`).
+- **Cell** — a numbered regional instance within a geo: `<geo><NN>` (`eu01`, `eu02`, `us01`), carried on **resources**. Dedicated (Layer 4) cells use a customer slug instead (`msly-cell-<customer>-<region>`). Shared (Layer 1) resources are cross-cell and carry **no** cell suffix.
+- **Physical Azure region** (e.g. Sweden Central — [ADR 0021](masterly-framework/docs/adr/0021-eu-control-plane-in-sweden-central.md)) is **never baked into a name** — it is the resource's native `location`, so a cell can move regions without a rename.
+
+Required Azure tags on every RG, now genuinely enforced by Azure Policy (`msly-required-rg-tags`, `Deny`, on both production subscriptions — see `masterly-platform-iac/bootstrap/policy/README.md`): **seven** — `cost-center`, `data-residency`, `deployment-model`, `owner`, `lifecycle`, `environment`, `region`. (This line listed only five until 2026-09-07; `platform-iac-resources.md` §1 is the source of truth.) **Azure reserves tag-name prefixes `azure`, `microsoft`, `windows`** — never start a tag name with them (use e.g. `cloud-region`, not `azure-region`).
+
+## Working style
+
+- **Foundation-first.** Get pluggable data storage, tenant isolation, deployment topology, and DBU instrumentation right *before* shipping features. Lesson from the PoC.
+- **Be explicit.** Solo founder + agents today; team later. Write as if a smart engineer (or agent) is picking this up cold next month.
+- **Push back on the user when their request conflicts with a hard constraint above.** Don't silently relax constraints.
+- **No code or infra changes without an ADR for cross-cutting decisions.** Repo-local changes don't need ADRs.
+- **Multi-repo work:** when a change spans repos, decide if the *decision* is shared (ADR in framework) or *implementation only* (per-repo PR). Don't duplicate the decision across repos.
+- **Customer docs ship with the product.** A customer-facing change (capability, API, MCP tool, config, deployment, or behavior) isn't done until the public docs in `masterly-web` reflect it — see the [customer-docs convention](masterly-framework/docs/conventions/customer-docs.md). Internal-only changes need none; say which in the PR.
+
+## Reading order for a new session
+
+If you're a Claude session just opening in any Masterly repo, read in this order:
+
+1. **This file** (project-wide guidance) — already auto-loaded
+2. **The local repo's `CLAUDE.md`** (per-repo specifics) — already auto-loaded
+3. **`masterly-framework/docs/architecture/build-order-and-phases.md`** — current roadmap and where this repo fits in
+4. **ADRs relevant to the work at hand** — see references in the local `CLAUDE.md`
+5. **The architecture doc(s) for the specific subsystem** — see `masterly-framework/docs/architecture/`

masterly-0.5.0/.claude/hooks/project-claude-md.sh

@@ -0,0 +1,299 @@
+#!/bin/bash
+# Install the project-wide CLAUDE.md where a Claude Code cloud session loads it (MAS-881).
+#
+# One source (the MAS-546 shape): the canonical copy of this hook is masterly-framework
+# repo-templates/project-claude-md/project-claude-md.sh. Every Masterly repository holds a
+# VERBATIM copy at .claude/hooks/project-claude-md.sh, registered as a synchronous SessionStart
+# hook by .claude/settings.json from the same template, with the vendored fallback beside it at
+# .claude/PROJECT-CLAUDE.md. Change it in masterly-framework and re-copy; never edit a copy in
+# place.
+#
+# Why this exists. Every Masterly repository's CLAUDE.md opens by saying that the project-wide
+# context is loaded from ../CLAUDE.md, one directory above the clone. On a developer's machine
+# that path is a symlink installed once by hand and verified (masterly-framework,
+# docs/conventions/project-wide-claude-md.md). A Claude Code cloud container is provisioned
+# fresh, with nobody at a shell to run `ln -s`, so the path was simply absent -- and every cloud
+# session ran without the hard architectural constraints, silently, because a session missing
+# this file has no way to notice. This hook is the cloud analogue of that one-time install.
+#
+# What it does, in order:
+#   1. Nothing unless CLAUDE_CODE_REMOTE is "true". It never touches a developer's machine,
+#      where the link is installed and verified by hand, and it prints nothing there.
+#   2. Derives every path; none is typed. The clones directory is the parent of
+#      CLAUDE_PROJECT_DIR, the repository root Claude Code hands a hook, and the target is
+#      <clones>/CLAUDE.md -- an ancestor of the working directory, which is what Claude Code
+#      loads. If CLAUDE_PROJECT_DIR is not set, nothing is derived and nothing is installed.
+#   3. Chooses the source, preferring the one that cannot drift:
+#        a. <clones>/masterly-framework/PROJECT-CLAUDE.md -- the tracked original, when the
+#           framework repository is cloned alongside;
+#        b. otherwise <repo>/.claude/PROJECT-CLAUDE.md -- the vendored copy shipped beside
+#           this hook: byte-identical to the tracked file when it was copied, and behind it
+#           from the tracked file's next change until it is re-copied. masterly-framework's
+#           CI proves the template equals the tracked file; nothing in a consuming repository's
+#           CI can see whether its copy is current.
+#   4. Links the target to the source by a relative path and reports one line on stdout,
+#      which the SessionStart hook contract adds to the session's context -- so the session
+#      can see which source it is reading, and a person can compare it with /context.
+#
+# What it never does: destroy content. The target is a place a person or a platform may have
+# put a file, so:
+#   * anything at the target that is not a symlink is left exactly as it is. A regular file
+#     whose bytes equal the chosen source is reported as an installed plain copy; anything else
+#     is reported as foreign, loudly, because sessions in that container are then loading a
+#     document this repository does not govern -- and it is still not replaced, because
+#     replacing it is the clobber this hook exists not to do;
+#   * a symlink that already resolves to the chosen source is left as it is;
+#   * a symlink that resolves anywhere else, or nowhere, is re-pointed. A symlink carries no
+#     content, so re-pointing it loses nothing; and in a remote container this hook is the only
+#     thing that makes one, so a link to a lesser source is this hook's own earlier choice in a
+#     container whose clone set has changed since (the container is cached between sessions).
+#
+# Synchronous, never async. Printing {"async": true} would let the session start before the
+# link exists, which is exactly the race this hook exists to close. The selftest asserts that
+# nothing this hook prints can be read as that marker.
+#
+# --selftest builds every case above in a temporary directory and asserts each outcome, so a
+# hook that has quietly stopped installing fails CI instead of passing for the wrong reason.
+# It exercises this file itself, with CLAUDE_CODE_REMOTE and CLAUDE_PROJECT_DIR set per case.
+
+set -euo pipefail
+
+TRACKED_NAME="PROJECT-CLAUDE.md"
+INSTALLED_NAME="CLAUDE.md"
+FRAMEWORK_DIR="masterly-framework"
+VENDORED_REL=".claude/$TRACKED_NAME"
+HOOK_REL=".claude/hooks/project-claude-md.sh"
+TAG="project-wide CLAUDE.md"
+
+# The physical path of an existing file or directory. `cd && pwd -P` rather than realpath or
+# readlink -f, which are not on every platform the selftest runs on.
+physical() {
+  if [ -d "$1" ]; then
+    (cd "$1" && pwd -P)
+  else
+    printf '%s/%s\n' "$(cd "$(dirname "$1")" && pwd -P)" "$(basename "$1")"
+  fi
+}
+
+# Where a symlink chain ends, as a physical path. Fails when it ends nowhere.
+resolve() {
+  local p=$1 t hops=0
+  while [ -L "$p" ]; do
+    t=$(readlink "$p")
+    case $t in
+      /*) p=$t ;;
+      *) p="$(dirname "$p")/$t" ;;
+    esac
+    hops=$((hops + 1))
+    [ "$hops" -le 40 ] || return 1
+  done
+  [ -e "$p" ] || return 1
+  physical "$p"
+}
+
+install() {
+  # 1. Remote only. Silent otherwise: a developer's session gets no line of noise.
+  [ "${CLAUDE_CODE_REMOTE:-}" = "true" ] || return 0
+
+  # 2. Derived paths, or nothing.
+  if [ -z "${CLAUDE_PROJECT_DIR:-}" ] || [ ! -d "$CLAUDE_PROJECT_DIR" ]; then
+    echo "$TAG: CLAUDE_PROJECT_DIR is not set to a directory, so no path can be derived; nothing installed."
+    return 0
+  fi
+  local project clones repo target link how source
+  project=$(physical "$CLAUDE_PROJECT_DIR")
+  clones=$(dirname "$project")
+  repo=$(basename "$project")
+  target="$clones/$INSTALLED_NAME"
+
+  # 3. The source, in preference order.
+  if [ -f "$clones/$FRAMEWORK_DIR/$TRACKED_NAME" ]; then
+    link="$FRAMEWORK_DIR/$TRACKED_NAME"
+    how="the tracked original in the $FRAMEWORK_DIR clone alongside; it cannot drift"
+  elif [ -f "$project/$VENDORED_REL" ]; then
+    link="$repo/$VENDORED_REL"
+    how="the vendored copy shipped in $repo; byte-identical to $FRAMEWORK_DIR/$TRACKED_NAME when it was copied, possibly behind it since"
+  else
+    echo "$TAG: no source. Neither $clones/$FRAMEWORK_DIR/$TRACKED_NAME nor $project/$VENDORED_REL exists, so nothing was installed at $target and this session has no project-wide context."
+    return 0
+  fi
+  source="$clones/$link"
+
+  # 4. The target, without destroying anything.
+  if [ -L "$target" ]; then
+    local current previous
+    if current=$(resolve "$target") && [ "$current" = "$(physical "$source")" ]; then
+      echo "$TAG: $target -> $link is already in place ($how). Installed by $repo/$HOOK_REL."
+      return 0
+    fi
+    previous=$(readlink "$target")
+    rm -f "$target"
+    ln -s "$link" "$target"
+    echo "$TAG: $target -> $link, re-pointed from $previous ($how). Installed by $repo/$HOOK_REL."
+    return 0
+  fi
+  if [ -e "$target" ]; then
+    if [ -f "$target" ] && cmp -s "$target" "$source"; then
+      echo "$TAG: $target is a plain file identical to $link and was left as it is ($how). Checked by $repo/$HOOK_REL."
+      return 0
+    fi
+    local msg
+    msg="$TAG: WARNING. $target exists, is not a symlink, and is not the tracked file. It was NOT replaced: sessions in this container load it instead of $link. Reported by $repo/$HOOK_REL."
+    echo "$msg"
+    echo "$msg" >&2
+    return 0
+  fi
+  ln -s "$link" "$target"
+  echo "$TAG: $target -> $link ($how). Installed by $repo/$HOOK_REL."
+}
+
+# --- selftest -------------------------------------------------------------------------------
+
+selftest() {
+  local self failures=0 total=0
+  self=$(physical "$0")
+  # Not local: the EXIT trap runs after this function has returned.
+  SELFTEST_TMP=$(mktemp -d)
+  trap 'rm -rf "$SELFTEST_TMP"' EXIT
+  local tmp=$SELFTEST_TMP
+
+  # A clones directory with a repository in it, holding the vendored copy, and optionally
+  # the framework clone beside it. Prints nothing; the caller knows the layout.
+  fixture() { # <clones> <with-framework: yes|no> <with-vendored: yes|no>
+    mkdir -p "$1/some-repo/.claude/hooks"
+    [ "$3" = "yes" ] && printf 'vendored copy\n' >"$1/some-repo/$VENDORED_REL"
+    if [ "$2" = "yes" ]; then
+      mkdir -p "$1/$FRAMEWORK_DIR"
+      printf 'tracked original\n' >"$1/$FRAMEWORK_DIR/$TRACKED_NAME"
+    fi
+    return 0
+  }
+
+  # Run the hook as Claude Code would: this file, with the two variables set per case. The
+  # environment running the selftest may itself be a cloud container with CLAUDE_CODE_REMOTE
+  # exported, so the "unset" case unsets it rather than inheriting it -- the first run of this
+  # selftest was in exactly such a container, and the case failed for that reason.
+  run() { # <remote value | unset> <project dir>
+    if [ "$1" = "unset" ]; then
+      env -u CLAUDE_CODE_REMOTE CLAUDE_PROJECT_DIR="$2" bash "$self" </dev/null 2>/dev/null
+    else
+      CLAUDE_CODE_REMOTE=$1 CLAUDE_PROJECT_DIR=$2 bash "$self" </dev/null 2>/dev/null
+    fi
+  }
+
+  check() { # <name> <exit status of the predicate>
+    total=$((total + 1))
+    if [ "$2" -eq 0 ]; then
+      echo "ok: $1"
+    else
+      echo "selftest FAIL: $1"
+      failures=$((failures + 1))
+    fi
+  }
+
+  # The predicates, named so each case reads as the claim it makes.
+  links_to() { [ -L "$1" ] && [ "$(readlink "$1")" = "$2" ]; }   # <path> <link text>
+  reads() { [ "$(cat "$1")" = "$2" ]; }                            # <path> <content>
+  plain_file() { [ ! -L "$1" ] && [ -f "$1" ]; }                   # <path>
+  absent() { [ ! -e "$1" ] && [ ! -L "$1" ]; }                     # <path>
+  says() { case $1 in *"$2"*) return 0 ;; esac; return 1; }        # <output> <fragment>
+  silent() { [ -z "$1" ]; }                                        # <output>
+  not_json() { case $1 in "{"*) return 1 ;; esac; return 0; }      # <output>
+
+  local c out t
+
+  # Remote, framework alongside: the link points at the tracked original.
+  c="$tmp/sibling"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  out=$(run true "$c/some-repo")
+  check "remote with the framework alongside links to the tracked original" \
+    "$(links_to "$t" "$FRAMEWORK_DIR/$TRACKED_NAME" && reads "$t" "tracked original"; echo $?)"
+  check "  ...and says so on stdout" "$(says "$out" "-> $FRAMEWORK_DIR/$TRACKED_NAME"; echo $?)"
+  check "  ...and prints nothing that reads as an async marker" "$(not_json "$out"; echo $?)"
+
+  # Running again changes nothing and says it is already in place.
+  out=$(run true "$c/some-repo")
+  check "a second run leaves a correct link alone" \
+    "$(links_to "$t" "$FRAMEWORK_DIR/$TRACKED_NAME" && says "$out" "already in place"; echo $?)"
+
+  # Remote, no framework: the link points at the vendored copy inside the repository.
+  c="$tmp/vendored"; t="$c/$INSTALLED_NAME"
+  fixture "$c" no yes
+  out=$(run true "$c/some-repo")
+  check "remote without the framework links to the vendored copy" \
+    "$(links_to "$t" "some-repo/$VENDORED_REL" && reads "$t" "vendored copy"; echo $?)"
+  check "  ...and says the copy may be behind" "$(says "$out" "possibly behind"; echo $?)"
+
+  # The framework appears later (a cached container whose clone set changed): re-pointed.
+  mkdir -p "$c/$FRAMEWORK_DIR"
+  printf 'tracked original\n' >"$c/$FRAMEWORK_DIR/$TRACKED_NAME"
+  out=$(run true "$c/some-repo")
+  check "a link to the vendored copy is re-pointed once the framework is alongside" \
+    "$(links_to "$t" "$FRAMEWORK_DIR/$TRACKED_NAME" && says "$out" "re-pointed from some-repo/$VENDORED_REL"; echo $?)"
+
+  # A dangling link is re-pointed.
+  c="$tmp/dangling"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  ln -s "no-such-file.md" "$t"
+  run true "$c/some-repo" >/dev/null
+  check "a dangling link is re-pointed" "$(links_to "$t" "$FRAMEWORK_DIR/$TRACKED_NAME"; echo $?)"
+
+  # Not remote: nothing happens and nothing is printed, whether unset or false.
+  c="$tmp/local-unset"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  out=$(run unset "$c/some-repo")
+  check "not remote (variable unset) installs nothing and prints nothing" \
+    "$(absent "$t" && silent "$out"; echo $?)"
+  c="$tmp/local-false"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  out=$(run false "$c/some-repo")
+  check "not remote (variable false) installs nothing and prints nothing" \
+    "$(absent "$t" && silent "$out"; echo $?)"
+
+  # A regular file at the target is never replaced -- whatever it holds.
+  c="$tmp/foreign"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  printf 'somebody else put this here\n' >"$t"
+  out=$(run true "$c/some-repo")
+  check "a foreign regular file at the target is not replaced" \
+    "$(plain_file "$t" && reads "$t" "somebody else put this here"; echo $?)"
+  check "  ...and is reported as not replaced" "$(says "$out" "NOT replaced"; echo $?)"
+  c="$tmp/plain-copy"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  printf 'tracked original\n' >"$t"
+  out=$(run true "$c/some-repo")
+  check "an identical plain copy at the target is left as a plain file" \
+    "$(plain_file "$t" && says "$out" "plain file identical"; echo $?)"
+
+  # No source at all: nothing is created, and the session is told it has no context.
+  c="$tmp/no-source"; t="$c/$INSTALLED_NAME"
+  fixture "$c" no no
+  out=$(run true "$c/some-repo")
+  check "no source anywhere installs nothing and says so" \
+    "$(absent "$t" && says "$out" "no source"; echo $?)"
+
+  # No project directory: nothing is derived.
+  c="$tmp/no-project"; t="$c/$INSTALLED_NAME"
+  fixture "$c" yes yes
+  out=$(CLAUDE_CODE_REMOTE=true bash "$self" </dev/null 2>/dev/null)
+  check "an unset CLAUDE_PROJECT_DIR derives nothing" \
+    "$(absent "$t" && says "$out" "CLAUDE_PROJECT_DIR is not set"; echo $?)"
+
+  # Synchronous by construction: no line of code in this file carries the async marker. The
+  # pattern is a key followed by a colon, which this line does not contain.
+  check "the hook never emits an async marker" \
+    "$(! grep -v '^ *#' "$self" | grep -qE '"async"[[:space:]]*:'; echo $?)"
+
+  if [ "$failures" -ne 0 ]; then
+    echo
+    echo "FAIL: $failures of $total selftest case(s) failed."
+    return 1
+  fi
+  echo "OK: $total selftest cases pass."
+}
+
+if [ "${1:-}" = "--selftest" ]; then
+  selftest
+else
+  install
+fi

masterly-0.5.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/project-claude-md.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

masterly-0.5.0/.github/dependabot.yml

@@ -0,0 +1,30 @@
+# Dependabot keeps the pinned action digests and the dependency manifests current.
+# Third-party actions in .github/workflows are pinned by commit SHA (a tag can be
+# moved; a SHA cannot), which makes them invisible to a human reading for staleness —
+# so the github-actions ecosystem below is what actually keeps them from rotting.
+#
+# Grouping (MAS-126): a wall of PRs each week gets skimmed, and a skimmed wall is how
+# a real one goes through unread. Actions group at every level, because actions/* ride
+# major tags deliberately and third-party ones are pinned by SHA, so the diff is a
+# digest either way and the version that changed is in the title. Code dependencies
+# group minor and patch only, so a major always arrives as its own readable PR.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      uv-minor-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      actions:
+        patterns: ["*"]
+        update-types: ["major", "minor", "patch"]

masterly-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+# Gates every pull request and every push to main. The package ships to PyPI from
+# release.yml, which builds whatever is on the tag — so this is the only place the
+# code is actually checked before it can get there.
+#
+# The floor is `requires-python` in pyproject: a client library is compiled by its
+# consumers' interpreters, not ours, so the oldest supported one has to run the suite.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# A re-push supersedes the run before it, so cancel the superseded PR run rather than pay
+# for a result nobody will read. Guarded to pull_request: a push to main — a deploy on some
+# repos, a tag build on others — must never be cancelled by whatever lands next. MAS-174.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Least privilege: the workflow grants nothing, and each job states the one scope it needs --
+# reading the repository for actions/checkout. Nothing here writes through the token, and
+# publishing lives in release.yml. Without a block the token's scopes are whatever the
+# repository setting says, which is not something a reader of this file can see.
+permissions: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        # The ends of the supported range. The versions between them share a bytecode
+        # generation with one of these two; widening the matrix buys little for the minutes.
+        python: ["3.10", "3.13"]
+    steps:
+      # persist-credentials: false — actions/checkout otherwise leaves the job's
+      # GITHUB_TOKEN in .git/config for the rest of the run, where any later step or
+      # third-party action can read it. Nothing in this repo pushes from CI, so the
+      # token has no job to do after the checkout. See masterly-framework
+      # docs/conventions/github-repo-settings.md, "Checkout credentials".
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10, pinned by digest
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run ruff check
+      # Strict, and on the package rather than the tests: a public client's types are
+      # part of its contract.
+      - run: uv run mypy src
+      - run: uv run pytest -q
+
+  # Every version on PyPI should be a tag here, and two are not: 0.1.1 and 0.2.0 were published
+  # from the private repository this one replaced, and the archive-and-recreate did not carry
+  # their tags across (MAS-503). RELEASING.md records what they were built from; this job keeps
+  # that record honest, and stops the package version from being set to one of those spent
+  # numbers. Its own job because it is standard-library only — no uv, no matrix, no network.
+  release-record:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # persist-credentials: false — actions/checkout otherwise leaves the job's
+      # GITHUB_TOKEN in .git/config for the rest of the run, where any later step or
+      # third-party action can read it. Nothing in this repo pushes from CI, so the
+      # token has no job to do after the checkout. See masterly-framework
+      # docs/conventions/github-repo-settings.md, "Checkout credentials".
+      #
+      # fetch-depth: 0 — the check asks whether a commit is in this repository's history, and
+      # in a shallow clone the answer is "no" for everything. It refuses to run shallow rather
+      # than answer vacuously, so the full history is not optional here.
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      # The detector before the thing it detects: synthetic records prove the check still
+      # rejects a missing, malformed or stale one, so a check that has quietly stopped
+      # checking fails here rather than passing the repository for the wrong reason.
+      - run: python3 scripts/check_release_record.py --selftest
+      - run: python3 scripts/check_release_record.py