Skip to content

Commit d02917d

Browse files
cdeustclaude
andauthored
fix: keep team decisions scoped to their project (#613)
* fix: separate project team decisions from global knowledge Signed-off-by: cdeust <[email protected]> * fix(scripts): drop typing.Self so the scope repair imports on Python 3.10 CI on Python 3.10 failed at collection of the two reclassification test modules: typing.Self exists from 3.11. The context manager now returns its concrete class under postponed annotations, with no new dependency. The validation record gains the owner-approved mapping of memory 4353879 and the targeted acceptance result on the restored snapshot. The mappings file itself names rows of one private store and stays outside the repository. Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> * test(scope): align the suite with project-scoped team decisions Four families of CI failures on this branch, none of them a product defect: - the frozen remember oracle (fixtures/w3_4) did not pass team_decision, so bulk and scalar rows differed by one key; - the agent briefing receipts tests seeded rows with no directory_context, which the project predicate now excludes by design; they seed the event's project, the team row is an is_team_decision row, and a row of another project is asserted absent (#611); - I2 allow-list line numbers in sqlite_store.py shifted by one; - scripts/reclassify_team_scope.py reaches core and now wires the composition root (#560). Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> * style(tests): reword a comment that ruff read as commented-out code Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> * test(hooks): seed briefing rows through one helper to stay under the method-size gate Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> * fix(scripts): undo only the ADR-0200 promotion, keep every other global row Review finding on #613: classify() cleared is_global on any resolved row the detector did not confirm, so a row made global by an explicit act was lost. A row now loses global scope only when it carries the defect signature, a decision written under an agent context. Other global rows are kept, listed under unexplained_global_ids, and the owner can clear one by id through clear_global_ids. An id cannot be both kept and cleared. Rerun on a fresh restore of the same archive: 93 changes, 0 on the second pass, 67 globals retained (46 unresolved, 6 left to the owner), row count unchanged. The validation record carries the new figures and no longer mentions unrelated private plans. Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> * docs(adr): ADR-1083 states the narrowed reclassification rule Refs #611 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NLvPnrr8Ab6cKPK1Kt3K7f Signed-off-by: cdeust <[email protected]> --------- Signed-off-by: cdeust <[email protected]> Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent 24c68c4 commit d02917d

32 files changed

Lines changed: 1318 additions & 114 deletions

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@ adheres to [Semantic Versioning](https://semver.org/).
66

77
## [Unreleased]
88

9+
### Fixed
10+
11+
- Team decisions retain their project scope (#611, ADR-1083). A separate
12+
`is_team_decision` marker grants visibility across project agents without
13+
setting `is_global`. SessionStart and agent briefings enforce project scope,
14+
ingestion preserves the directory, and initialization no longer promotes
15+
team decisions to global scope. Existing global rows have a dry-run-first
16+
reclassification script.
17+
918
## [4.23.0] - 2026-09-17
1019

1120
### Added
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1083-separate-project-team-decisions-from-global-knowledge.md; ADR-1083. Read-only mirror: edit the canonical wiki page. -->
2+
3+
---
4+
created: 2026-09-17
5+
kind: adr
6+
number: 1083
7+
status: proposed
8+
tags: [memory-scoping, team-decisions, issue-611]
9+
title: Separate project team decisions from global knowledge
10+
---
11+
# ADR-1083: Separate project team decisions from global knowledge
12+
13+
## Status
14+
15+
Proposed for owner review in issue #611. Supersedes the team-to-global
16+
mapping in ADR-0200 and the team-decision exception in ADR-1080.
17+
18+
## Evidence
19+
20+
Issue #611 records memory 4353879 from japonais-2027 injected into
21+
anthropic-partnership by both session hooks. `team_scope.is_team_decision`
22+
and `global_detector.resolve_global_scope` promote deliberate decisions
23+
under an agent context to `is_global`, which bypasses project isolation.
24+
The intended visibility across agents therefore also crosses projects.
25+
26+
## Decision
27+
28+
A team decision is visible to every agent within its project. Persist
29+
`is_team_decision` independently of `is_global` on both backends. Team
30+
visibility relaxes only the agent predicate. Project visibility continues
31+
to require the recorded project root or an ancestor, as in ADR-1080.
32+
33+
Reserve `is_global` for an explicit global write or a positive result from
34+
the existing content detector. A row may carry both flags when justified
35+
independently. No detector threshold changes are part of this correction.
36+
The Team Decisions query applies project scope before ordering and limit.
37+
Ordinary hook recall treats team decisions as ordinary project memories.
38+
39+
Reclassify legacy global rows with an idempotent, explicit operator script.
40+
Run a dry-run first and verify a PostgreSQL custom-format backup before
41+
applying to production. Legacy rows do not persist the reason for the
42+
global flag. Operators can preserve IDs known to have been explicitly
43+
global through `keep_global_ids`, and the content detector also preserves a
44+
row. Otherwise `is_global` is cleared only for the rows ADR-0200 promoted: a
45+
decision written under an agent context, which receives the team marker. Any
46+
other global row is kept and reported, because an explicit act the script
47+
cannot see made it global; the owner can clear one by ID through
48+
`clear_global_ids`. Preserve row IDs, history and supersession.
49+
50+
An empty directory context is never a project wildcard. Resolve it only
51+
from a domain with an unambiguous, verified project-directory mapping,
52+
or an explicit owner-approved memory-ID mapping recorded in the run report.
53+
Leave unresolved rows global and enumerate their IDs for owner review.
54+
Do not derive project ownership by guessing from prose or path suffixes.
55+
56+
## Verification
57+
58+
Both backends must exclude a project-A team decision from project B and
59+
include it in project A for another agent. Explicit globals remain visible
60+
in both. A second reclassification run changes no rows. Production signal:
61+
4353879 is absent under anthropic-partnership and present under japonais-2027;
62+
the former's Team Decisions block contains no japonais-2027 rows.
63+
64+
## Consequences
65+
66+
Schema migrations add a default-false team flag without rewriting legacy
67+
scope automatically. The separate data operation is inspectable and
68+
reversible from its backup. Unresolved legacy globals remain an explicit
69+
owner-review list. Existing explicit global semantics are preserved.
Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Issue 611: scope repair validation and operator procedure
2+
3+
Base: `24c68c4a` (v4.23.0). Measured 2026-09-17.
4+
Decision: ADR-1083, proposed for owner review. This change is not released.
5+
6+
## Regression evidence
7+
8+
The original `remember` regression failed because an agent decision returned
9+
`is_global=True`. After separating the flags, the affected PostgreSQL suite
10+
passes 182 tests. SQLite passes 175 tests, with seven PostgreSQL-only tests
11+
skipped. The sandbox-only SQLite run reports PostgreSQL unavailable; the
12+
PostgreSQL execution uses a separately created scratch database. The
13+
reclassification script suite additionally passes 24 tests on PostgreSQL,
14+
including transaction failure and archive validation paths.
15+
16+
Independent review reproduced an ingestion privilege regression: an `auto`
17+
write was persisted as `deliberate`, and initialization then granted team
18+
visibility. Four of eight origin/class reopen cases failed before persisting
19+
the class. All eight pass after the fix on both backends. SQLite also tests
20+
an upgrade from the old schema. The PostgreSQL upgrade was exercised on a
21+
full restore of the pre-change production archive, including the existing
22+
`current_memories` view.
23+
24+
## Production snapshot experiment
25+
26+
The custom-format production archive was restored in full into an isolated
27+
PostgreSQL database; `pg_restore` exited zero. Production was not reclassified.
28+
The script also checks for memories table data and decodes the full archive
29+
before allowing PostgreSQL apply. This validates readability, not that an
30+
arbitrary supplied archive belongs to the selected database; the operator
31+
must create and retain the target's own backup as below.
32+
33+
| Measurement | Result |
34+
| --- | --- |
35+
| Current non-benchmark global candidates | 160 |
36+
| Dry-run changes | 98 |
37+
| Applied changes on the restored copy | 98 |
38+
| Changes proposed on the second run | 0 |
39+
| Retained globals | 62 |
40+
| Retained globals with unresolved project | 47 |
41+
| Total rows before and after repair | 47,490 |
42+
43+
All fields other than `is_global`, `is_team_decision`, and `directory_context`
44+
had identical ordered aggregate hashes before and after repair:
45+
`f66cfb02e0c7996857ccfe74b311e667`. This includes content, IDs, and supersession.
46+
The comparison ran before the acceptance hooks, which can record receipts.
47+
48+
## Approved mapping and remaining owner decisions
49+
50+
All 47 originally empty `directory_context` rows also had an empty `domain`.
51+
On 2026-09-17 the owner explicitly approved assigning memory 4353879 to
52+
`/Users/cdeust/Developments/japonais-2027`. The operator input is a mappings
53+
file of the form `{"domains": {}, "memories": {"<id>": "<project root>"},
54+
"keep_global_ids": []}`. It names rows of one private store, so it is kept
55+
outside the repository.
56+
57+
Applied to the already reclassified snapshot, this changes one additional
58+
row to `is_global=false`, `is_team_decision=true`, with the approved directory.
59+
The next pass changes zero rows. Across both passes, 99 of the original 160
60+
candidates lose global scope; 61 remain global, including 46 unresolved rows.
61+
The actual auto-recall launcher now excludes the Score audit decision from
62+
anthropic-partnership and includes it in japonais-2027. Both processes exit
63+
zero. This verifies the specific 4353879 acceptance signal on the snapshot.
64+
65+
Production remains unreclassified pending deployment of the reviewed code.
66+
The parent Team Decisions query still returns unresolved row 4356519, whose
67+
project requires separate owner review. The full SessionStart launcher
68+
validation timed out after 60 seconds; direct query and subprocess fixture
69+
tests do not replace final installed-plugin acceptance.
70+
71+
Remaining unresolved IDs, left global without changing their project:
72+
73+
4254394, 4342464, 4343116, 4347543, 4349020, 4349043, 4349560, 4349960, 4349976, 4350007, 4351552, 4351562, 4351771, 4352557, 4352618, 4353539, 4353601, 4353612, 4354421, 4354708, 4355514, 4355539, 4355775, 4356057, 4356262, 4356365, 4356519, 4356548, 4356730, 4357099, 4359407, 4359553, 4359753, 4359754, 4359755, 4359773, 4360000, 4361139, 4362817, 4365424, 4365650, 4367130, 4367241, 4367268, 4367557, 4367684
74+
75+
The legacy row does not store whether `is_global` was explicit or inferred.
76+
Use `keep_global_ids` for rows independently known to have been explicitly
77+
global. The script otherwise applies the existing content detector exactly
78+
as requested by the reclassification plan.
79+
80+
## Operator procedure
81+
82+
1. Review ADR-1083 and the unresolved ID list. Start with the approved mapping
83+
file described above. Additional mappings require owner approval. Use a private file
84+
with verified `domains` and approved `memories` (decimal ID keys) maps
85+
to existing canonical absolute project directories, plus `keep_global_ids`.
86+
Empty mapping keys and inferred ownership from prose are rejected.
87+
2. Deploy the reviewed code and schema before production reclassification.
88+
Old installations still run the team-to-global backfill at initialization
89+
and can reverse a data-only repair. Do not mix the repaired data with old
90+
writers. The owner controls merge, release and installed-plugin updates.
91+
3. Create a fresh `pg_dump -Fc -f cortex-before-611.dump cortex`. Restore it
92+
to a separate scratch database and verify successful completion.
93+
4. Run the script with the explicit target and inspect its JSON report:
94+
95+
```sh
96+
python scripts/reclassify_team_scope.py --database-url postgresql:///cortex \
97+
--mappings /private/path/scope-mappings.json
98+
```
99+
100+
5. Apply that reviewed mapping with `--apply --backup /private/path/cortex-before-611.dump`.
101+
Repeat the dry-run and require `change_count: 0`. Preserve the reports and
102+
backup outside Git. SQLite uses `--sqlite-path` instead of `--database-url`.
103+
6. Run both acceptance hooks from the updated installed plugin. Require
104+
4353879 absent in anthropic-partnership and present in japonais-2027, and
105+
no japonais-2027 row in the parent's Team Decisions block. Do not claim
106+
the issue fixed in a release before this.
107+
108+
## Rerun after review (2026-09-17)
109+
110+
The review of #613 found that `classify()` cleared `is_global` on any resolved
111+
row the detector did not confirm, including rows the ADR-0200 promotion could
112+
not have produced (no agent context, or no decision content). Those rows were
113+
made global by an explicit act the script cannot see. The rule is now narrower:
114+
only a decision written under an agent context loses global scope. Every other
115+
global row is kept and listed under `unexplained_global_ids`, and the owner can
116+
clear one through `clear_global_ids` in the mappings file.
117+
118+
The figures above predate that change. The same archive was restored into a
119+
fresh database and the whole sequence repeated with the approved mapping of
120+
4353879 supplied from the first pass:
121+
122+
| Measurement | Result |
123+
| --- | --- |
124+
| Global candidates | 160 |
125+
| Dry-run changes | 93 |
126+
| Applied changes | 93 |
127+
| Changes proposed on the second run | 0 |
128+
| Retained globals | 67 |
129+
| of which unresolved project | 46 |
130+
| of which kept as not produced by the defect | 6 |
131+
| Non-benchmark rows before and after | 47,041 |
132+
133+
The six kept rows are 4349818, 4353551, 4353795, 4353809, 4353915 and 4361406.
134+
Each has an agent context and content the decision cue does not match, so the
135+
script leaves the call to the owner. The apply step refused to run until the
136+
`is_team_decision` column existed on the restored copy, as designed.
137+
138+
## Python compatibility
139+
140+
CI Python 3.10 exposed a collection error from importing `typing.Self`, which
141+
is unavailable in that supported version. The database context manager now
142+
uses its concrete class as a postponed return annotation, with no new dependency.
143+
144+
## Completion ledger
145+
146+
| Changed behavior or failure path | Evidence |
147+
| --- | --- |
148+
| Separate global resolution and team classification | core global-scope and handler team-scope regressions |
149+
| Trusted ingest class/origin survives reopening | eight-case matrix, both backends |
150+
| Persist marker and upgrade existing schema/view | SQLite schema-upgrade test; restored PostgreSQL archive |
151+
| Initialization does not promote team rows to global | backfill tests, including zero second-run row count |
152+
| Session hooks enforce project predicate before limit | team-project hook tests and real subprocess tests |
153+
| Agent briefing scopes both selection passes | PostgreSQL team-project regression |
154+
| Explicit global and detector behavior preserved | global detector tests and cross-project hook fixtures |
155+
| Domain mapping, approved ID mapping, unresolved rows | script classifier and mapping validation tests |
156+
| Dry-run, second-run idempotence, history/benchmark exclusion | SQLite script tests and restored snapshot experiment |
157+
| Transaction rollback and marker refusal | real PostgreSQL and SQLite script tests |
158+
| Missing/invalid backup, missing table data, full decode | script backup validation tests and full archive restore |
159+
160+
No merge, release or production reclassification is performed by this change.

‎mcp_server/core/global_detector.py‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -262,18 +262,15 @@ def resolve_global_scope(
262262
tags: list[str],
263263
*,
264264
explicit: bool,
265-
team_decision: bool,
266265
) -> tuple[bool, str]:
267266
"""Return (is_global, reason) for a new memory.
268267
269-
An explicit request wins, then team propagation of decisions (the caller
270-
evaluates team_scope.is_team_decision), then the content detector.
268+
Only explicit cross-project scope or the content detector sets global scope.
269+
source: ADR-1083
271270
272271
source: ADR-0200
273272
source: ADR-0184"""
274273
if explicit:
275274
return True, "explicit"
276-
if team_decision:
277-
return True, "team_decision"
278275
detected, _score, reason = detect_global(content, tags)
279276
return detected, reason

‎mcp_server/core/memory_ingest.py‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
)
1313
from mcp_server.observability import silent_failure
1414
from mcp_server.core import knowledge_graph, write_post_store
15-
from mcp_server.core.team_scope import propagates_to_team
15+
from mcp_server.core.team_scope import is_team_decision
1616

1717

1818
def ingest_memory(
@@ -88,8 +88,11 @@ def ingest_memory(
8888
# source: ADR-0200
8989

9090
agent_ctx = memory.get("agent_context", "")
91-
is_global = memory.get("is_global", False) or propagates_to_team(
92-
auto_protect, agent_ctx
91+
team_decision = not is_benchmark and is_team_decision(
92+
chunk_content,
93+
memory.get("capture_origin", "unknown"),
94+
memory.get("write_class", "deliberate"),
95+
agent_ctx,
9396
)
9497

9598
mid = store.insert_memory(
@@ -108,7 +111,10 @@ def ingest_memory(
108111
"is_benchmark": is_benchmark,
109112
"is_protected": auto_protect,
110113
"agent_context": agent_ctx,
111-
"is_global": is_global,
114+
"is_global": memory.get("is_global", False),
115+
"is_team_decision": team_decision, # source: ADR-1083
116+
"directory_context": memory.get("directory_context", ""),
117+
"write_class": memory.get("write_class", "deliberate"),
112118
# source: ADR-0200
113119
"capture_origin": memory.get("capture_origin", "unknown"),
114120
}

‎mcp_server/core/team_scope.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
"""Team scope of decisions: Transactive Memory Systems (Wegner 1987).
22
33
The team knows WHAT was decided regardless of WHO decided it, so a
4-
decision written under an agent context is marked is_global.
4+
decision written under an agent context is marked is_team_decision.
5+
Project scope remains unchanged (source: ADR-1083).
56
67
source: ADR-0200"""
78

‎mcp_server/handlers/remember.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -286,9 +286,6 @@ async def _handler_impl(
286286
content,
287287
tags,
288288
explicit=bool(is_global),
289-
team_decision=is_team_decision(
290-
content, resolved_origin, resolved_write_class, agent_topic or ""
291-
),
292289
)
293290

294291
mid: int | None
@@ -335,6 +332,9 @@ async def _handler_impl(
335332
emb_engine,
336333
agent_context=agent_topic,
337334
is_global=is_global,
335+
team_decision=is_team_decision(
336+
content, resolved_origin, resolved_write_class, agent_topic or ""
337+
),
338338
created_at=created_at,
339339
write_class=resolved_write_class,
340340
origin=resolved_origin,

‎mcp_server/handlers/remember_helpers.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -694,6 +694,7 @@ def insert_and_post_process(
694694
emb_engine: EmbeddingEngine,
695695
agent_context: str = "",
696696
is_global: bool = False,
697+
team_decision: bool = False,
697698
created_at: str | None = None,
698699
write_class: str = "deliberate",
699700
origin: str = capture_origin.ORIGIN_UNKNOWN,
@@ -742,6 +743,7 @@ def insert_and_post_process(
742743
)
743744
record["agent_context"] = agent_context
744745
record["is_global"] = is_global
746+
record["is_team_decision"] = team_decision # source: ADR-1083
745747
record["write_class"] = write_class
746748
# source: ADR-0438
747749
record["capture_origin"] = origin

‎mcp_server/hooks/agent_briefing.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
from __future__ import annotations
3737

3838
import json
39+
import os
3940
import re
4041
import sys
4142
from pathlib import Path
@@ -56,6 +57,7 @@
5657
_fetch_agent_context,
5758
)
5859
from mcp_server.infrastructure.config import CLAUDE_DIR
60+
from mcp_server.shared.project_scope import resolve_project_root
5961

6062
__all__ = [
6163
"_DATABASE_URL",
@@ -168,7 +170,9 @@ def process_event(event: dict[str, Any]) -> None:
168170
sys.exit(0)
169171

170172
try:
171-
memories = _fetch_agent_context(conn, agent_name, keywords)
173+
memories = _fetch_agent_context(
174+
conn, agent_name, keywords, resolve_project_root(event, os.environ)
175+
)
172176
if not memories:
173177
_log(f"skip: no relevant memories for {agent_name}")
174178
sys.exit(0)

0 commit comments

Comments
 (0)