fix: TASK-005 review F-A — attribute config provenance to env-file vs shell env

Review of `doctor config` found values set in the workspace env file
(.teaagent/env) were mislabeled `env:VAR`, indistinguishable from a real shell
var — defeating the feature's purpose (accurate provenance) for exactly the
"hidden config source" case it exists to surface.

Fix: resolve_config_provenance now snapshots the shell env before loading the
env file and parses the file's exports, so it can attribute each env-layer value
to `env:VAR` (shell) or `env-file:.teaagent/env` (file). A var set in both is
attributed to the shell, which wins (the file never overwrites the shell).
Refactored _load_env_file to share a pure _parse_env_file_exports helper.

- teaagent/ergonomics/workspace_defaults.py: _parse_env_file_exports +
  env-file/shell attribution in resolve_config_provenance.
- doctor_config: precedence list + note mention env-file.
- Test: env-file value -> env-file source; same key in shell -> shell wins.
- docs/cli.md + spec updated.

Residuals documented, not fixed (review F-C/F-D): automation_webhook_url is not
redacted (could embed a token; consistent with existing redaction policy); a
malformed numeric env var raises in resolve_config_provenance and
load_workspace_defaults (pre-existing, unchanged).

Constraint: provenance labeling only; load_workspace_defaults output unchanged (same values, same precedence); _load_env_file behavior unchanged (now via shared parser).
Tested: tests/test_workspace_defaults_toml.py 23 passed (incl. new env-file attribution test); mypy clean; doctor config smoke shows env-file vs env: correctly.
Not-tested: full suite not run on 3.12 (hypothesis missing in 3.14 sandbox).
Confidence: high
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: johnteee

docs/cli.md

@@ -362,9 +362,11 @@ teaagent doctor env-order --root .
 ```
 
 Config provenance — show the effective value **and its source** for each config
-key (which layer won: `default`, `config:config.toml`, `config:config.json`, or
-`env:VAR`). CLI flags override these at run time but are noted, not resolved
-(doctor is not the agent run). Secrets are redacted while their source is kept:
+key (which layer won: `default`, `config:config.toml`, `config:config.json`,
+`env-file:.teaagent/env`, or `env:VAR` for the shell environment). A var set in
+both the shell and `.teaagent/env` is attributed to the shell, which wins. CLI
+flags override these at run time but are noted, not resolved (doctor is not the
+agent run). Secrets are redacted while their source is kept:
 
 ```bash
 teaagent doctor config --root .

docs/generated/docs-inventory.md

@@ -186,7 +186,7 @@ Do not edit this file manually — regenerate instead.
 | `architecture/seven-control-loops-teaagent-integration-map-2026-06-05.md` | archive | 9282 | `6d85e832f8eb` |
 | `audit-events.md` | working | 2376 | `b83066076fba` |
 | `backlog-priority.md` | working | 30003 | `a9576322cca1` |
-| `cli.md` | working | 36243 | `0e6c5bdeb9c8` |
+| `cli.md` | working | 36383 | `db50960ce4e2` |
 | `cloud-deployment.md` | working | 9431 | `50f6461a2077` |
 | `context-bus-and-federated-sync.md` | working | 1564 | `2dde6eed4bf8` |
 | `daily-driver-current-status.md` | working | 17015 | `3fc1c142eb49` |
@@ -562,7 +562,7 @@ Do not edit this file manually — regenerate instead.
 | `strategy/agent-ecosystem-core-values-2026-06-05.md` | archive | 12861 | `23194f9dc611` |
 | `strategy/competitive-analysis-and-positioning-2026-06-06.md` | archive | 67553 | `7c78b145750a` |
 | `strategy/daily-driver-roadmap-rationale-2026-06-04.md` | archive | 5053 | `3b6cdeed6d2e` |
-| `strategy/harness-first-direction-2026-06-13.md` | constitution | 20253 | `b632a377aa9e` |
+| `strategy/harness-first-direction-2026-06-13.md` | constitution | 20826 | `b4a9469900b8` |
 | `strategy/implementation-roadmap-with-effort-impact-2026-06-06.md` | archive | 58270 | `fb0af11ee7a6` |
 | `strategy/malleable-governed-agent-harness-2026-06-03.md` | archive | 15446 | `eccbc0177490` |
 | `strategy/phase-0-to-phase-1-outlook-2026-06-04.md` | archive | 5314 | `374a502902b6` |

docs/strategy/harness-first-direction-2026-06-13.md

@@ -317,6 +317,14 @@ spine-wide.
   redaction). This command is the citeable closure mechanism for any
   owner-logged config-source-confusion friction (the log's evidence entries
   remain owner-seeded per TASK-007).
+- **Review fix (F-A):** provenance distinguishes the shell environment
+  (`env:VAR`) from the workspace env file (`env-file:.teaagent/env`); a var set
+  in both is attributed to the shell, which wins. (Initially both were
+  mislabeled `env:` — defeating the point for env-file values.) Residuals,
+  documented not fixed: `automation_webhook_url` is not redacted (could embed a
+  token; consistent with existing redaction policy); a malformed numeric env var
+  raises in both `resolve_config_provenance` and `load_workspace_defaults`
+  (pre-existing, unchanged behavior).
 
 ### TASK-006: RunEvent taxonomy ADR + M0 dual-write spike
 - Goal: ADR for event schema; spine emitting alongside audit on the proof scenario.

teaagent/cli/_handlers/_doctor.py

@@ -400,13 +400,16 @@ def doctor_config(args: argparse.Namespace) -> int:
         'precedence': [
             'cli',
             'env',
+            'env-file:.teaagent/env',
             'config:config.json',
             'config:config.toml',
             'default',
         ],
         'note': (
             'CLI flags override env/config/default at run time; doctor shows the '
-            'non-CLI layers (it is not the agent run).'
+            'non-CLI layers (it is not the agent run). "env" is the shell '
+            'environment; "env-file:.teaagent/env" is the workspace env file '
+            '(the shell wins when both define a var).'
         ),
         'config': config,
     }

teaagent/ergonomics/workspace_defaults.py

@@ -89,16 +89,16 @@ def _read_json(path: Path) -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
-def _load_env_file(root: str | Path) -> None:
-    """Load ``.teaagent/env`` into ``os.environ`` without overwriting existing vars.
+def _parse_env_file_exports(root: str | Path) -> dict[str, str]:
+    """Parse ``.teaagent/env`` ``export KEY=value`` lines into a dict.
 
-    This makes API keys written by ``teaagent setup --write-env`` available
-    to the LLM adapter layer without requiring the user to manually
-    ``source .teaagent/env`` in their shell.
+    Pure: does not touch ``os.environ``. Used both to load the file and to
+    attribute config provenance to the env file vs. the real shell environment.
     """
     env_path = Path(root).resolve() / '.teaagent' / 'env'
     if not env_path.is_file():
-        return
+        return {}
+    exports: dict[str, str] = {}
     for raw_line in env_path.read_text(encoding='utf-8').splitlines():
         line = raw_line.strip()
         if not line.startswith('export '):
@@ -108,13 +108,26 @@ def _load_env_file(root: str | Path) -> None:
         if not sep:
             continue
         key = key.strip()
-        if not key or key in os.environ:
+        if not key:
             continue
         value = raw_value.strip()
         # shlex.quote() wraps in single quotes; unstrip them
         if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
             value = value[1:-1]
         if value:
+            exports[key] = value
+    return exports
+
+
+def _load_env_file(root: str | Path) -> None:
+    """Load ``.teaagent/env`` into ``os.environ`` without overwriting existing vars.
+
+    This makes API keys written by ``teaagent setup --write-env`` available
+    to the LLM adapter layer without requiring the user to manually
+    ``source .teaagent/env`` in their shell.
+    """
+    for key, value in _parse_env_file_exports(root).items():
+        if key not in os.environ:
             os.environ[key] = value
 
 
@@ -150,8 +163,23 @@ def resolve_config_provenance(root: str | Path = '.') -> dict[str, dict[str, Any
     """
     root_path = Path(root).resolve()
     tea_dir = root_path / '.teaagent'
+
+    # Snapshot the real shell env BEFORE loading the workspace env file, and
+    # parse the file's exports, so env-layer values can be attributed to the
+    # right source: a var already in the shell is `env:VAR`; one only the file
+    # provides is `env-file:.teaagent/env`. (The file never overwrites the shell,
+    # so shell wins when both define a key.)
+    shell_env_keys = set(os.environ)
+    env_file_exports = _parse_env_file_exports(root_path)
     _load_env_file(root_path)
 
+    def _env_source(env_name: str) -> str:
+        if env_name in shell_env_keys:
+            return f'env:{env_name}'
+        if env_name in env_file_exports:
+            return 'env-file:.teaagent/env'
+        return f'env:{env_name}'
+
     prov: dict[str, dict[str, Any]] = {
         key: {'value': value, 'source': 'default'}
         for key, value in DEFAULT_KEYS.items()
@@ -165,12 +193,15 @@ def resolve_config_provenance(root: str | Path = '.') -> dict[str, dict[str, Any
 
     for key, env_name in _ENV_MAP.items():
         if os.environ.get(env_name):
-            prov[key] = {'value': os.environ[env_name], 'source': f'env:{env_name}'}
+            prov[key] = {
+                'value': os.environ[env_name],
+                'source': _env_source(env_name),
+            }
 
     for key, (env_name, coerce) in _ENV_ONLY.items():
         raw = os.environ.get(env_name)
         if raw:
-            prov[key] = {'value': coerce(raw), 'source': f'env:{env_name}'}
+            prov[key] = {'value': coerce(raw), 'source': _env_source(env_name)}
 
     return prov
 

tests/test_workspace_defaults_toml.py

@@ -273,6 +273,35 @@ def test_resolve_config_provenance_env_overrides_config(
     assert prov['provider'] == {'value': 'from_env', 'source': 'env:TEAAGENT_PROVIDER'}
 
 
+def test_resolve_config_provenance_distinguishes_env_file_from_shell(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A value from .teaagent/env is sourced to the file; a shell var wins and is
+    sourced to the shell (review F-A)."""
+    from teaagent.ergonomics.workspace_defaults import resolve_config_provenance
+
+    tea = tmp_path / '.teaagent'
+    tea.mkdir()
+    (tea / 'env').write_text(
+        'export TEAAGENT_MODEL=model-from-envfile\n'
+        'export TEAAGENT_PROVIDER=provider-from-envfile\n',
+        encoding='utf-8',
+    )
+    # model only in the env file; provider also set in the shell (shell wins).
+    monkeypatch.delenv('TEAAGENT_MODEL', raising=False)
+    monkeypatch.setenv('TEAAGENT_PROVIDER', 'provider-from-shell')
+
+    prov = resolve_config_provenance(tmp_path)
+    assert prov['model'] == {
+        'value': 'model-from-envfile',
+        'source': 'env-file:.teaagent/env',
+    }
+    assert prov['provider'] == {
+        'value': 'provider-from-shell',
+        'source': 'env:TEAAGENT_PROVIDER',
+    }
+
+
 def test_load_workspace_defaults_matches_provenance_values(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: