narrativetrace 0.4.0__tar.gz → 0.4.2__tar.gz

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/LICENSE

@@ -7,7 +7,7 @@ Parameters
 
 Licensor:             Empower Agile
 
-Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.4.0. The Licensed Work is (c) 2026 Empower Agile.
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.4.2. The Licensed Work is (c) 2026 Empower Agile.
 
 Additional Use Grant: You may make production use of the Licensed Work for any
                       purpose, including internal use and use in products and
@@ -18,7 +18,7 @@ Additional Use Grant: You may make production use of the Licensed Work for any
                       parties as a logging, tracing, or code-narrative product
                       or service.
 
-Change Date:          Four years from the date the Licensed Work is published. (2030-10-16 for this version)
+Change Date:          Four years from the date the Licensed Work is published. (2030-10-20 for this version)
 
 Change License:       Apache License, Version 2.0
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace
-Version: 0.4.0
+Version: 0.4.2
 Summary: Narrative execution tracing for Python — human- and LLM-readable traces
 Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
 Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace"
-version = "0.4.0"
+version = "0.4.2"
 description = "Narrative execution tracing for Python — human- and LLM-readable traces"
 readme = "README.md"
 requires-python = ">=3.12"

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/__init__.py

@@ -97,7 +97,7 @@ from narrativetrace.values import (
     StringVal,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "NOOP_CONTEXT",

narrativetrace-0.4.2/src/narrativetrace/_generated.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Licensed under the Business Source License 1.1 (see LICENSE); Change Date: four
+# years from publication; Change License: Apache-2.0
+# Copyright (c) 2026 Empower Agile
+"""Exclusion list 1 -- what is structurally never a business boundary in Python.
+
+Built in and not configurable: no setting re-enables a member, and nothing here is reported.
+Membership is a structural property of the object, never a vendor's module name:
+
+* a target whose type is defined by the interpreter itself (``type(target).__module__ ==
+  "builtins"``: ``list``, ``dict``, ``str``, ...) -- C-accelerated, no business logic to narrate;
+* a ``functools.partial`` / ``functools.partialmethod`` object, as a target or as a member -- a
+  library-built forwarder whose only behaviour is the callable it wraps;
+* a member the C runtime supplies (builtin functions and bound builtin methods, method wrappers,
+  slot wrappers, method descriptors) -- ``types.BuiltinFunctionType`` and its siblings;
+* a member whose ``__name__`` is not an identifier (``<lambda>``, ``<genexpr>``): a name no
+  ``def`` statement can produce, only the compiler;
+* a ``_private`` / ``__dunder__`` member -- machinery the runtime calls on its own behalf.
+
+**@llmNote** ``functools.lru_cache`` wrappers and ``functools.wraps``-decorated functions are
+deliberately NOT members: ``wraps`` makes the wrapper indistinguishable from the function it
+wraps, and a cached business method is still a boundary the reader wants to see.
+"""
+
+from __future__ import annotations
+
+import functools
+import types
+
+GENERATED_MEMBERS: tuple[tuple[str, str], ...] = (
+    (
+        "builtins.*",
+        "The target's type is defined by the interpreter itself (`list`, `dict`, `str`)",
+    ),
+    (
+        "functools.partial",
+        "A `functools.partial` / `partialmethod` object, as a target or as a member",
+    ),
+    (
+        "types.BuiltinFunctionType",
+        "A member the C runtime supplies: builtin functions, bound builtin methods, method "
+        "wrappers, slot wrappers, method descriptors",
+    ),
+    ("<lambda>", "A member whose `__name__` is not an identifier (`<lambda>`, `<genexpr>`)"),
+    ("_name", "A `_private` or `__dunder__` member: machinery the runtime calls for itself"),
+)
+"""List 1 as the configuration guide publishes it: (what is never traced, its structural
+property). A test holds the guide's table to this tuple."""
+
+_C_RUNTIME_CALLABLES: tuple[type, ...] = (
+    types.BuiltinFunctionType,
+    types.MethodWrapperType,
+    types.WrapperDescriptorType,
+    types.MethodDescriptorType,
+)
+_FUNCTOOLS_FORWARDERS: tuple[type, ...] = (functools.partial, functools.partialmethod)
+
+
+def is_generated_target(target: object) -> bool:
+    """True when ``target`` itself is never a business boundary (see the module docstring)."""
+    return type(target).__module__ == "builtins" or isinstance(target, _FUNCTOOLS_FORWARDERS)
+
+
+def is_generated_member(name: str, member: object) -> bool:
+    """True when member ``name`` (already fetched as ``member``) is never a business boundary."""
+    if name.startswith("_"):
+        return True
+    if isinstance(member, _C_RUNTIME_CALLABLES + _FUNCTOOLS_FORWARDERS):
+        return True
+    return not getattr(member, "__name__", "x").isidentifier()

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/agents/add-narrative-tracing/SKILL.md

@@ -8,7 +8,8 @@ description: "Installs NarrativeTrace into a Python project and gets it to a fir
 ## 1. Install with the real toolchain
 
 ```bash
-uv sync --all-packages
+uv add narrativetrace
+uv sync
 ```
 
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
@@ -19,6 +20,10 @@ if bad:
 sys.exit(1 if bad else 0)
 '`
 
+**failure:** the project is managed by pip, poetry or pdm rather than uv, or `uv add` just wrote a uv.lock beside another manager's lockfile — this page spells its commands in uv, and the project uses another manager. Fix: remove the uv.lock uv wrote; a project on pip, poetry or pdm adds the same distribution with its own command and checks with its own clean install
+
+**failure:** `uv add` exits 2 with `No pyproject.toml found` — the directory is no Python project yet, and `uv add` does not create one. Fix: run `uv init --bare` once, then `uv add narrativetrace` again
+
 **failure:** a sibling narrativetrace-* package disagrees on version — an installed distribution outside the lockstep version the other narrativetrace-* packages share. Fix: run the narrativetrace-doctor skill's toolchain.package-versions check, then pin every narrativetrace-* dependency to the same version and `uv sync`
 
 ## 2. Wire the frameworks this project already uses
@@ -41,7 +46,7 @@ sys.exit(1 if bad else 0)
 
 ## 3. First trace: wrap, call, render, run
 
-**when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a demo main.py: run the application the way it already runs, exercise one real boundary, and read that request's trace; the verify below is for the standalone script, and in an existing application the step is done when that request's trace is in the output; otherwise create the smallest script as follows
+**when:** if the project already has tests — a test directory, a runner's table in its pyproject.toml or a test runner among its dependencies — and the doctor reports a test integration for that runner, do not add a demo script: run one existing test through that integration with output on, which writes that test's narrative files, .md and .nt, under the integration's output directory — the files narrativetrace-doctor, -verify, -debug and -explain read; print the rendered file so the trace is also on the console; the step is done when that test's files exist; a project whose runner has no integration keeps that runner and takes the console path below; if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a demo main.py: run the application the way it already runs, exercise one real boundary, and read that request's trace; the verify below is for the standalone script, and in an existing application the step is done when that request's trace is in the output; otherwise create the smallest script as follows; nothing is written to disk by this script — the application's log is the record once the logging bridge in the later step is wired; this page never adds a test runner or a test to a project that has none
 
 <!-- snippet: examples/sixty_seconds/main.py -->
 ```python
@@ -76,7 +81,35 @@ print(IndentedTextRenderer().render(context.capture_trace()))
 
 **failure:** a *args method's parameters render as one args: [...] value — inspect.signature has nothing named to reconstruct per-argument that Python itself does not have. Fix: supply explicit names: @traced("first", "second", ...) above the method
 
-## 4. Send it to your logger
+**failure:** a bare function, a lambda or a functools.partial gives no spans at all, or a span carries the wrong class name — a span is named after type(target).__name__, and trace_object never traces a function, lambda or partial. Fix: trace an instance of a class of your own, or pass class_name="..." to trace_object to show a different name
+
+**failure:** trace_object returns the object unwrapped and stderr says it cannot trace it (excluded module ...) — the class is defined under a module prefix on the exclude list, whose shipped default covers test and mocking libraries and APM runtimes. Fix: wrap a class of your own, or set NARRATIVETRACE_EXCLUDE (or the exclude key) to the full list you want, which replaces the default
+
+## 4. Name the service
+
+<!-- snippet: examples/sixty_seconds/main_named_service.py -->
+```python
+# main.py
+from narrativetrace import ContextVarNarrativeContext, ServiceIdentity
+
+context = ContextVarNarrativeContext(service_identity=ServiceIdentity("orders", "1.4.0", "prod"))
+```
+<!-- /snippet -->
+
+**done when:** the service has its own real name — set once, where the context is built or in the environment the service runs in (NARRATIVETRACE_SERVICE_NAME), never a placeholder; in an existing application the line that builds the context changes, no second context is added
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+by_id = {f["id"]: f for f in report["findings"]}
+finding = by_id.get("config.service-identity")
+if finding is None or finding["status"] != "pass":
+    print(finding["fix"] if finding else "the doctor has no config.service-identity finding")
+sys.exit(0 if finding is not None and finding["status"] == "pass" else 1)
+'`
+
+**failure:** traces say unknown_service:python on the platform — nobody named the service, so the fallback name is all there is. Fix: pass service_identity=ServiceIdentity("orders") to the ContextVarNarrativeContext, or set NARRATIVETRACE_SERVICE_NAME (and NARRATIVETRACE_SERVICE_VERSION, NARRATIVETRACE_ENVIRONMENT) in the environment the service runs in
+
+## 5. Send it to your logger
 
 **when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a second main.py or a second logging setup: add the filter and the export_to_logger call to the application's own logging configuration and the boundary you exercised; the verify below is for the standalone script, and in an existing application the step is done when that boundary's trace reaches the application's own logger; otherwise create the smallest script as follows
 
@@ -132,7 +165,7 @@ export_to_logger(trace)  # new: sends the same captured trace through the config
 
 **verify:** `uv run python main_with_logger.py`
 
-## 5. Run the doctor and resolve its findings
+## 6. Run the doctor and resolve its findings
 
 ```bash
 uv run narrativetrace doctor || true
@@ -141,10 +174,10 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
-## 6. Install the skills for next time
+## 7. Install the skills for next time
 
 ```bash
 uv run narrativetrace init --dry-run
@@ -169,7 +202,7 @@ sys.exit(0 if result.returncode == 0 and shown and untouched else 1)
 
 ## Always
 
-- Reinstall clean (`uv sync`) rather than trusting whatever is already in the virtual environment. (a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
+- Check the install with a clean `uv sync` after adding the package, rather than trusting whatever is already in the virtual environment. (`uv add` installs; the clean sync is the check that the lockfile it wrote reproduces -- a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
 
 ## Never
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/agents/narrativetrace-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: narrativetrace-doctor
-description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
+description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed in this project and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
 ---
 
 # narrativetrace-doctor
@@ -14,7 +14,7 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
 **failure:** the CLI's JSON output does not parse, or is missing findings — the CLI crashed instead of reporting a finding. Fix: re-run `uv run narrativetrace doctor --json` directly and read the raw output -- a crash here is a doctor bug, never a project finding

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/agents/narrativetrace-explain/SKILL.md

@@ -57,7 +57,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/t
 
 ## 8. Explain the run by span id, and mark what you inferred
 
-**done when:** the explanation is in the user's own words and in the trace's own order: the calls the flow made, each claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt or .md read in this session count — the branch it took, and where the time went when that was the question. Every sentence that goes beyond what the trace shows is marked as an inference, and the last part names what was NOT observed: the code no span covers, because only wrapped or intercepted code has one
+**done when:** the explanation is in the user's own words and in the trace's own order: the calls the flow made, each claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt or .md read in this session count — the branch it took, and where the time went when that was the question. Every sentence that goes beyond what the trace shows is marked as an inference, and the last part names what was NOT observed: the code no span covers, because only wrapped or intercepted code has one, and the branches this run did not take
 
 ## Which flavour answers which question
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/agents/narrativetrace-feedback/SKILL.md

@@ -14,7 +14,7 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
 **failure:** the CLI is not found, or the project has no pyproject.toml — NarrativeTrace is not installed in this project's environment. Fix: report under the prompt or library category instead -- those do not need a doctor report

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/agents/narrativetrace-verify/SKILL.md

@@ -65,7 +65,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/s
 
 ## 5. Open values on the span that looks wrong, and only there
 
-**when:** only when the structural read named a span that does not match the intent; otherwise go on to the pin
+**when:** when the structural read named a span that does not match the intent, or the shape matches but a symptom points at data — an assertion failed on a value, the output is wrong — then open the one span the symptom points at; otherwise go on to the pin
 
 ```bash
 uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/traces").rglob("*.md")), sep="\n")'
@@ -75,7 +75,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/t
 
 ## 6. Fix, re-run, read again
 
-**when:** only when the structural read named a span that does not match the intent; otherwise go on to the pin
+**when:** only when the structural read named a span that does not match the intent, or the value read in step 5 was wrong; otherwise go on to the pin
 
 ```bash
 uv run pytest <the smallest test that drives the real path>
@@ -118,7 +118,7 @@ uv run narrativetrace-approve
 
 ## 11. Report what the trace showed
 
-**done when:** two sentences on what the trace showed, every claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt that was read count — with the .nt attached or quoted; 'tests pass' alone is not the report
+**done when:** two sentences on what the trace showed on the path this run took, every claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt that was read count — with the .nt attached or quoted; the report names the branches and inputs this run did not exercise, because one trace shows one path, not every execution; 'tests pass' alone is not the report
 
 ## Which flavour answers which question
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/catalogue.json

@@ -3,7 +3,7 @@
   "skills": [
     {
       "name": "narrativetrace-doctor",
-      "description": "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it.",
+      "description": "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed in this project and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it.",
       "agents": "agents/narrativetrace-doctor/SKILL.md",
       "claude": "claude/narrativetrace-doctor/SKILL.md"
     },

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/claude/add-narrative-tracing/SKILL.md

@@ -10,7 +10,8 @@ allowed-tools: Bash(uv *), Bash(git *)
 ## 1. Install with the real toolchain
 
 ```bash
-uv sync --all-packages
+uv add narrativetrace
+uv sync
 ```
 
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
@@ -21,6 +22,10 @@ if bad:
 sys.exit(1 if bad else 0)
 '`
 
+**failure:** the project is managed by pip, poetry or pdm rather than uv, or `uv add` just wrote a uv.lock beside another manager's lockfile — this page spells its commands in uv, and the project uses another manager. Fix: remove the uv.lock uv wrote; a project on pip, poetry or pdm adds the same distribution with its own command and checks with its own clean install
+
+**failure:** `uv add` exits 2 with `No pyproject.toml found` — the directory is no Python project yet, and `uv add` does not create one. Fix: run `uv init --bare` once, then `uv add narrativetrace` again
+
 **failure:** a sibling narrativetrace-* package disagrees on version — an installed distribution outside the lockstep version the other narrativetrace-* packages share. Fix: run the narrativetrace-doctor skill's toolchain.package-versions check, then pin every narrativetrace-* dependency to the same version and `uv sync`
 
 ## 2. Wire the frameworks this project already uses
@@ -43,7 +48,7 @@ sys.exit(1 if bad else 0)
 
 ## 3. First trace: wrap, call, render, run
 
-**when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a demo main.py: run the application the way it already runs, exercise one real boundary, and read that request's trace; the verify below is for the standalone script, and in an existing application the step is done when that request's trace is in the output; otherwise create the smallest script as follows
+**when:** if the project already has tests — a test directory, a runner's table in its pyproject.toml or a test runner among its dependencies — and the doctor reports a test integration for that runner, do not add a demo script: run one existing test through that integration with output on, which writes that test's narrative files, .md and .nt, under the integration's output directory — the files narrativetrace-doctor, -verify, -debug and -explain read; print the rendered file so the trace is also on the console; the step is done when that test's files exist; a project whose runner has no integration keeps that runner and takes the console path below; if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a demo main.py: run the application the way it already runs, exercise one real boundary, and read that request's trace; the verify below is for the standalone script, and in an existing application the step is done when that request's trace is in the output; otherwise create the smallest script as follows; nothing is written to disk by this script — the application's log is the record once the logging bridge in the later step is wired; this page never adds a test runner or a test to a project that has none
 
 <!-- snippet: examples/sixty_seconds/main.py -->
 ```python
@@ -78,7 +83,35 @@ print(IndentedTextRenderer().render(context.capture_trace()))
 
 **failure:** a *args method's parameters render as one args: [...] value — inspect.signature has nothing named to reconstruct per-argument that Python itself does not have. Fix: supply explicit names: @traced("first", "second", ...) above the method
 
-## 4. Send it to your logger
+**failure:** a bare function, a lambda or a functools.partial gives no spans at all, or a span carries the wrong class name — a span is named after type(target).__name__, and trace_object never traces a function, lambda or partial. Fix: trace an instance of a class of your own, or pass class_name="..." to trace_object to show a different name
+
+**failure:** trace_object returns the object unwrapped and stderr says it cannot trace it (excluded module ...) — the class is defined under a module prefix on the exclude list, whose shipped default covers test and mocking libraries and APM runtimes. Fix: wrap a class of your own, or set NARRATIVETRACE_EXCLUDE (or the exclude key) to the full list you want, which replaces the default
+
+## 4. Name the service
+
+<!-- snippet: examples/sixty_seconds/main_named_service.py -->
+```python
+# main.py
+from narrativetrace import ContextVarNarrativeContext, ServiceIdentity
+
+context = ContextVarNarrativeContext(service_identity=ServiceIdentity("orders", "1.4.0", "prod"))
+```
+<!-- /snippet -->
+
+**done when:** the service has its own real name — set once, where the context is built or in the environment the service runs in (NARRATIVETRACE_SERVICE_NAME), never a placeholder; in an existing application the line that builds the context changes, no second context is added
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+by_id = {f["id"]: f for f in report["findings"]}
+finding = by_id.get("config.service-identity")
+if finding is None or finding["status"] != "pass":
+    print(finding["fix"] if finding else "the doctor has no config.service-identity finding")
+sys.exit(0 if finding is not None and finding["status"] == "pass" else 1)
+'`
+
+**failure:** traces say unknown_service:python on the platform — nobody named the service, so the fallback name is all there is. Fix: pass service_identity=ServiceIdentity("orders") to the ContextVarNarrativeContext, or set NARRATIVETRACE_SERVICE_NAME (and NARRATIVETRACE_SERVICE_VERSION, NARRATIVETRACE_ENVIRONMENT) in the environment the service runs in
+
+## 5. Send it to your logger
 
 **when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a second main.py or a second logging setup: add the filter and the export_to_logger call to the application's own logging configuration and the boundary you exercised; the verify below is for the standalone script, and in an existing application the step is done when that boundary's trace reaches the application's own logger; otherwise create the smallest script as follows
 
@@ -134,7 +167,7 @@ export_to_logger(trace)  # new: sends the same captured trace through the config
 
 **verify:** `uv run python main_with_logger.py`
 
-## 5. Run the doctor and resolve its findings
+## 6. Run the doctor and resolve its findings
 
 ```bash
 uv run narrativetrace doctor || true
@@ -143,10 +176,10 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
-## 6. Install the skills for next time
+## 7. Install the skills for next time
 
 ```bash
 uv run narrativetrace init --dry-run
@@ -171,7 +204,7 @@ sys.exit(0 if result.returncode == 0 and shown and untouched else 1)
 
 ## Always
 
-- Reinstall clean (`uv sync`) rather than trusting whatever is already in the virtual environment. (a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
+- Check the install with a clean `uv sync` after adding the package, rather than trusting whatever is already in the virtual environment. (`uv add` installs; the clean sync is the check that the lockfile it wrote reproduces -- a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
 
 ## Never
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/claude/narrativetrace-doctor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: narrativetrace-doctor
-description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
-when_to_use: "A project already has NarrativeTrace installed and something about it is not working, or an agent wants a pre-flight check before wiring it into new code."
+description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed in this project and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
+when_to_use: "A project already has NarrativeTrace installed and something about it is not working, or an agent wants a pre-flight check before wiring it into new code. Also when a user installed these skills as a personal plugin in their agent rather than in this project: a plugin install is invisible to this check by design, and only a project install reaches teammates and other agents."
 allowed-tools: Bash(uv *), Bash(git *)
 ---
 
@@ -16,7 +16,7 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
 **failure:** the CLI's JSON output does not parse, or is missing findings — the CLI crashed instead of reporting a finding. Fix: re-run `uv run narrativetrace doctor --json` directly and read the raw output -- a crash here is a doctor bug, never a project finding

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/claude/narrativetrace-explain/SKILL.md

@@ -58,7 +58,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/t
 
 ## 8. Explain the run by span id, and mark what you inferred
 
-**done when:** the explanation is in the user's own words and in the trace's own order: the calls the flow made, each claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt or .md read in this session count — the branch it took, and where the time went when that was the question. Every sentence that goes beyond what the trace shows is marked as an inference, and the last part names what was NOT observed: the code no span covers, because only wrapped or intercepted code has one
+**done when:** the explanation is in the user's own words and in the trace's own order: the calls the flow made, each claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt or .md read in this session count — the branch it took, and where the time went when that was the question. Every sentence that goes beyond what the trace shows is marked as an inference, and the last part names what was NOT observed: the code no span covers, because only wrapped or intercepted code has one, and the branches this run did not take
 
 ## Which flavour answers which question
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/claude/narrativetrace-feedback/SKILL.md

@@ -15,7 +15,7 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 21 else 0)
 '`
 
 **failure:** the CLI is not found, or the project has no pyproject.toml — NarrativeTrace is not installed in this project's environment. Fix: report under the prompt or library category instead -- those do not need a doctor report

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/_skills/claude/narrativetrace-verify/SKILL.md

@@ -66,7 +66,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/s
 
 ## 5. Open values on the span that looks wrong, and only there
 
-**when:** only when the structural read named a span that does not match the intent; otherwise go on to the pin
+**when:** when the structural read named a span that does not match the intent, or the shape matches but a symptom points at data — an assertion failed on a value, the output is wrong — then open the one span the symptom points at; otherwise go on to the pin
 
 ```bash
 uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/traces").rglob("*.md")), sep="\n")'
@@ -76,7 +76,7 @@ uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/t
 
 ## 6. Fix, re-run, read again
 
-**when:** only when the structural read named a span that does not match the intent; otherwise go on to the pin
+**when:** only when the structural read named a span that does not match the intent, or the value read in step 5 was wrong; otherwise go on to the pin
 
 ```bash
 uv run pytest <the smallest test that drives the real path>
@@ -119,7 +119,7 @@ uv run narrativetrace-approve
 
 ## 11. Report what the trace showed
 
-**done when:** two sentences on what the trace showed, every claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt that was read count — with the .nt attached or quoted; 'tests pass' alone is not the report
+**done when:** two sentences on what the trace showed on the path this run took, every claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt that was read count — with the .nt attached or quoted; the report names the branches and inputs this run did not exercise, because one trace shows one path, not every execution; 'tests pass' alone is not the report
 
 ## Which flavour answers which question
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/config.py

@@ -60,9 +60,12 @@ def _load_toml(path: Path) -> dict[str, Any] | None:
 
 
 def _canonical(value: Any) -> str:
-    """Renders a TOML scalar the way a properties file would carry it (``true``, not ``True``)."""
+    """Renders a TOML value the way a properties file would carry it (``true``, not ``True``; an
+    array as its items joined by ``;``, the delimiter list-valued keys such as ``exclude`` use)."""
     if isinstance(value, bool):
         return "true" if value else "false"
+    if isinstance(value, list):
+        return ";".join(_canonical(item) for item in value)
     return str(value)
 
 

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/context.py

@@ -223,8 +223,21 @@ class NarrativeContext(ABC):
         """Returns the current trace id, generating one eagerly if absent."""
         return TraceId.generate()
 
-    def adopt_trace_id(self, trace_id: TraceId) -> None:
-        """Adopts an inbound (e.g. W3C ``traceparent``) trace id for the current scope."""
+    def adopt_trace_id(
+        self,
+        trace_id: TraceId,
+        remote_parent_span_id: SpanId | None = None,
+        trace_flags: int = 0,
+    ) -> None:
+        """Adopts an inbound (e.g. W3C ``traceparent``) trace id for the current scope.
+
+        ``remote_parent_span_id`` is the caller's span the inbound request came from (the
+        ``traceparent`` parent-id field). When given, this scope's root spans record it as their
+        ``parent_span_id``, so a consumer that follows parent ids links this service's trace to the
+        caller's; it never appears as a span in this scope's own tree. ``trace_flags`` is the
+        ``traceparent`` flags byte (bit 0 = sampled); every span this scope creates carries it as
+        :attr:`~narrativetrace.span.SpanContext.trace_flags`.
+        """
 
     def story_id(self) -> str | None:
         """Story id derived from the first root-level call, or ``None``."""
@@ -290,6 +303,8 @@ class _TraceStack:
     trace_id: TraceId | None = None
     scoped_parent: SpanId | None = None
     snapshot_parent: SpanId | None = None
+    remote_parent: SpanId | None = None
+    trace_flags: int = 0
     story_id: str | None = None
     chapter_id: str | None = None
     metadata: _RequestMetadata = _EMPTY_METADATA
@@ -490,6 +505,11 @@ class ContextVarNarrativeContext(NarrativeContext):
 
     The stack lives in a :class:`contextvars.ContextVar`, so a fresh thread and a freshly
     created asyncio task each lazily obtain their own isolated stack while sharing one store.
+
+    ``service_identity`` names the service on every span. Left ``None`` it is read from
+    ``NARRATIVETRACE_SERVICE_NAME`` / ``NARRATIVETRACE_SERVICE_VERSION`` /
+    ``NARRATIVETRACE_ENVIRONMENT`` (:meth:`ServiceIdentity.from_environment`); with neither, traces
+    say ``unknown_service:python``.
     """
 
     def __init__(
@@ -499,7 +519,9 @@ class ContextVarNarrativeContext(NarrativeContext):
         store: EventStore | None = None,
     ) -> None:
         self._config = config if config is not None else NarrativeTraceConfig()
-        self._service_identity = service_identity
+        self._service_identity = (
+            service_identity if service_identity is not None else ServiceIdentity.from_environment()
+        )
         self._store = store if store is not None else EventStore()
         self._span_contexts: dict[SpanId, SpanContext] = {}
         self._span_lock = threading.Lock()
@@ -556,7 +578,9 @@ class ContextVarNarrativeContext(NarrativeContext):
         active = stack.peek_active()
         if active is not None:
             return active
-        return stack.snapshot_parent
+        if stack.snapshot_parent is not None:
+            return stack.snapshot_parent
+        return stack.remote_parent
 
     def _create_span_context(
         self, stack: _TraceStack, parent_span_id: SpanId | None
@@ -571,6 +595,7 @@ class ContextVarNarrativeContext(NarrativeContext):
             trace_id=trace_id,
             span_id=SpanId.generate(),
             parent_span_id=parent_span_id,
+            trace_flags=stack.trace_flags,
             http_method=metadata.http_method,
             http_route=metadata.http_route,
             client_ip=metadata.client_ip,
@@ -744,8 +769,16 @@ class ContextVarNarrativeContext(NarrativeContext):
             stack.trace_id = TraceId.generate()
         return stack.trace_id
 
-    def adopt_trace_id(self, trace_id: TraceId) -> None:
-        self._get_stack().trace_id = trace_id
+    def adopt_trace_id(
+        self,
+        trace_id: TraceId,
+        remote_parent_span_id: SpanId | None = None,
+        trace_flags: int = 0,
+    ) -> None:
+        stack = self._get_stack()
+        stack.trace_id = trace_id
+        stack.remote_parent = remote_parent_span_id
+        stack.trace_flags = trace_flags
 
     def story_id(self) -> str | None:
         return self._get_stack().story_id

{narrativetrace-0.4.0 → narrativetrace-0.4.2}/src/narrativetrace/doctor/environment.py

@@ -22,8 +22,10 @@ import sys
 import tomllib
 from importlib import metadata as importlib_metadata
 from pathlib import Path
+from typing import Literal
 
 from narrativetrace.config import ConfigResolver
+from narrativetrace.exclusions import ExcludedModules
 from narrativetrace_tooling.doctor.types import DoctorSnapshot, Env, PackageInfo
 from narrativetrace_tooling.frameworks.manifests import is_manifest
 from narrativetrace_tooling.init import (
@@ -222,6 +224,24 @@ class _Walker:
                 self._visit_file(entry)
 
 
+def _resolve_exclude(
+    resolver: ConfigResolver, env: Env
+) -> tuple[tuple[str, ...] | None, Literal["default", "configured"], str | None]:
+    """The snapshot's exclusion-list fields: (effective list, where it came from, parse error).
+
+    ``env`` is consulted first so a snapshot built from an explicit environment reports that
+    environment; otherwise the resolver's own chain (process environment, config file) decides."""
+    given = env.get("NARRATIVETRACE_EXCLUDE")
+    try:
+        excluded = (
+            ExcludedModules.parse(given) if given is not None else ExcludedModules.resolve(resolver)
+        )
+    except ValueError as error:
+        return None, "default", str(error)
+    configured = given is not None or resolver.resolve("exclude", None) is not None
+    return excluded.prefixes, "configured" if configured else "default", None
+
+
 def build_snapshot(cwd: str, env: Env) -> DoctorSnapshot:
     """Builds a :class:`~narrativetrace_tooling.doctor.types.DoctorSnapshot` from the real
     filesystem rooted at ``cwd``."""
@@ -230,6 +250,7 @@ def build_snapshot(cwd: str, env: Env) -> DoctorSnapshot:
     config = resolver.file_values
     output_dir_name = str(config.get("output_dir") or "narrative-traces")
     approved_dir_name = str(config.get("approved_dir") or "test-narratives")
+    exclude = _resolve_exclude(resolver, env)
     walker = _Walker(root, output_dir_name, approved_dir_name)
     walker.walk()
     project = _read_project_state(root)
@@ -248,4 +269,7 @@ def build_snapshot(cwd: str, env: Env) -> DoctorSnapshot:
         pointer_readings=_resolve_pointer_readings(project),
         catalogue_skill_names=_resolve_catalogue_skill_names(),
         narrativetrace_version=project_family_version(),
+        effective_exclude=exclude[0],
+        exclude_source=exclude[1],
+        exclude_error=exclude[2],
     )