@awebai/oats 0.37.0 → 0.38.1

package/lib/teams.mjs

@@ -1,26 +1,29 @@
 /**
- * Team model v2 (docs/design/2026-09-27-team-model-v2.md, option B), pure.
+ * Team model 3 (docs/design/2026-10-02-team-model-3.md, awebai/oats#484), pure.
  *
  * Where teams live:
- *   - the committed oats-workspace.yaml `teams.<label> = { description?, team? }`: SHARED teams (edited
- *     by PR). A shared team without `team` is declared but not yet created (unmapped);
- *   - the deployment's oats-local.yaml `teams.<label> = { team, description? }`: LOCAL teams, plus
- *     `defaultTeam: <label>`, `souls.teams: { "*" | <soul key>: [labels] }` and
- *     `souls.default: { <soul key>: <label> }`.
- * A soul key is the soul's bare name, or `<package>/<soul>` for a package soul.
+ *   - the committed oats-workspace.yaml: SHARED teams `teams.<label> = { description?, team? }` (a shared
+ *     team without `team` is declared but not yet created: unmapped); `defaultTeam: <label>`, the
+ *     workspace's fallback default; `localTeams: true|false` (absent: false), whether deployments may
+ *     declare their own teams; and `souls: { <pattern>: { default?, teams?: [labels] | "any" } }`;
+ *   - the deployment's oats-local.yaml, only when the workspace says `localTeams: true` (or there is no
+ *     workspace file: the standalone view): LOCAL teams `teams.<label> = { team, description? }` and
+ *     `defaultTeam: <label>`. Otherwise they are refused (E_WORKSPACE_SCHEMA reason local-teams-closed).
+ * A soul's key is its qualified name (teamKeyOf): `<package>/<soul>` or `<member>/<soul>`.
  *
- * Resolution: labels = shared ∪ local (a label in both is `team-label-collision`; the SHARED definition
- * wins). defaultOf(soul) = souls.default[soul] ?? defaultTeam; a soul's teams = {defaultOf} ∪
- * souls.teams["*"] ∪ souls.teams[soul]. An undeclared label the soul reaches is E_TEAM_UNKNOWN; a
- * souls.default outside the soul's teams is E_TEAM_NOT_ELIGIBLE.
+ * Resolution: a `souls:` pattern is the soul's key, then `<member|package>/*`, then "*"; the most specific
+ * one that exists gives the soul's teams outright (no merging), and the most specific one that sets a
+ * `default` gives its default. Default, in order: that `default` (from "soul"); else the local
+ * `defaultTeam` when local teams are allowed ("deployment"); else the workspace's `defaultTeam`
+ * ("workspace"); else none. A soul's teams: its default, plus its pattern's `teams` ("any": every shared
+ * team), plus every local team when local teams are allowed. A label in both files is
+ * `team-label-collision` (the SHARED definition wins). Workspace labels are validated when the file is
+ * read (lib/workspace.mjs); a local default no file declares is E_TEAM_UNKNOWN.
  *
- * Rows (docs/desktop-cli-api.md, Team model v2): TeamRow { label, team, default, from: shared|local },
- * the default first, then by label. Reports carry unmapped rows (team null); OATS_TEAMS and
- * instance.json carry mapped rows only. DefaultTeam { label, team, from: deployment|soul } | null.
- *
- * Team model 3 (0.38.0, awebai/oats#484) moves these choices into the committed workspace file. 0.36.x and
- * 0.37.x validate its keys (lib/workspace.mjs) without applying them, and warn about what 0.38.0 will refuse
- * (migrationProblems: team-model-3-migration).
+ * Rows (docs/desktop-cli-api.md, Teams): TeamRow { label, team, default, from: shared|local, via }, `via`
+ * ⊂ ["default", "workspace", "local"] in that order (why the soul may join it); the default first, then
+ * by label. Reports carry unmapped rows (team null); OATS_TEAMS and instance.json carry mapped rows only.
+ * DefaultTeam { label, team, from: soul|deployment|workspace } | null.
  */
 import { oatsError } from "./errors.mjs";
 
@@ -41,12 +44,16 @@ export const LOCAL_FILE = "oats-local.yaml";
  *  validates its own id shape. Keep equal to docs/oats-{local,workspace}.schema.json. */
 export const TEAM_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$/;
 /** What 0.30 removed, named by the schema problems that replace them. */
-export const TEAM_MEMBERSHIP_MOVED = "team membership is local since 0.30: `oats soul teams`";
+export const TEAM_MEMBERSHIP_MOVED = "a soul's teams are decided by souls: in oats-workspace.yaml (team model 3, OATS 0.38.0)";
 export const BY_TEAM_REMOVED = "byTeam was removed in 0.30: a team's provider id is teams.<label>.team (oats-workspace.yaml for a shared team, oats-local.yaml for a local one)";
 
 const UNMAPPED_FIX = "its owner runs `oats aweb setup`, then commits the id";
+const CLOSED_FIX = "either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml";
 
-/** The deployment's teams from the committed workspace and oats-local.yaml (either may be null). */
+/**
+ * The deployment's teams from the committed workspace and oats-local.yaml (either may be null; a null
+ * workspace is the standalone view, which has no workspace rules).
+ */
 export function teamModel(workspace, local, { workspaceKey = null } = {}) {
   const shared = new Map(), localTeams = new Map();
   for (const [label, def] of Object.entries(isObject(workspace?.teams) ? workspace.teams : {})) {
@@ -56,76 +63,124 @@ export function teamModel(workspace, local, { workspaceKey = null } = {}) {
   for (const [label, def] of Object.entries(isObject(local?.teams) ? local.teams : {})) {
     localTeams.set(label, { label, team: str(def?.team), description: str(def?.description), from: "local", at: `${LOCAL_FILE}#/teams/${pointerKey(label)}` });
   }
-  const souls = isObject(local?.souls) ? local.souls : {};
-  const has = (v, k) => isObject(v) && Object.hasOwn(v, k);
+  const standalone = !isObject(workspace);
+  const allowed = standalone || workspace.localTeams === true;
+  const localKeys = ["teams", "defaultTeam"].filter((k) => isObject(local) && Object.hasOwn(local, k));
   return {
     shared, local: localTeams,
     labels: new Map([...localTeams, ...shared]), // the committed definition wins a collision
-    defaultTeam: str(local?.defaultTeam),
-    souls: { teams: isObject(souls.teams) ? souls.teams : {}, default: isObject(souls.default) ? souls.default : {} },
-    // Team model 3 (0.38.0) moves these keys; 0.36.x and 0.37.x only warn (migrationProblems). `localTeams` is
-    // the workspace's answer, null without a workspace file (the standalone view has no workspace rules).
-    migration: {
-      soulKeys: ["teams", "default"].filter((k) => has(local?.souls, k)).map((k) => `souls.${k}`),
-      teamKeys: ["teams", "defaultTeam"].filter((k) => has(local, k)),
-      localTeams: isObject(workspace) ? workspace.localTeams === true : null,
-    },
+    // true | false (the workspace's answer), null in the standalone view.
+    localTeams: standalone ? null : allowed,
+    // The oats-local.yaml keys the workspace refuses (local-teams-closed); [] when allowed.
+    closedKeys: allowed ? [] : localKeys,
+    localDefault: allowed ? str(local?.defaultTeam) : null,
+    workspaceDefault: standalone ? null : str(workspace.defaultTeam),
+    souls: !standalone && isObject(workspace.souls) ? workspace.souls : {},
+    soulsAt: `${workspaceKey ? `${workspaceKey}:` : ""}oats-workspace.yaml#/souls`,
   };
 }
 
-/** The key a soul has in souls.teams / souls.default. */
+/** The key a soul has in oats-local.yaml souls.launch: its bare name, or `<package>/<soul>` for a package soul. */
 export function soulKeyOf(soulEntry) {
   return typeof soulEntry?.package === "string" && typeof soulEntry.qualifiedName === "string" ? soulEntry.qualifiedName : soulEntry.name;
 }
+/** A member's name: the last segment of its repo key, without `.git` (`souls.disabled` and team keys use it). */
+export function memberNameOf(key) {
+  return String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") || String(key);
+}
+/** A soul's key in the workspace's `souls:` (team model 3): `<package>/<soul>` for a package soul,
+ *  `<member>/<soul>` for any other (its repository's name), as `souls.disabled` qualifies it. */
+export function teamKeyOf(soulEntry) {
+  if (typeof soulEntry?.package === "string") return typeof soulEntry.qualifiedName === "string" ? soulEntry.qualifiedName : `${soulEntry.package}/${soulEntry.name}`;
+  return `${memberNameOf(soulEntry?.repoKey ?? "")}/${soulEntry?.name}`;
+}
+
+/**
+ * What a team model v2 oats-local.yaml (`souls.teams`, `souls.default`) gave each soul, as the workspace
+ * `souls:` that gives the same (0.38.0's removed-key refusal prints it): "*" keeps `souls.teams["*"]`; each
+ * soul named gets its default and "*" ∪ its own list, since patterns never merge. A bare (member) soul
+ * name becomes `<member>/<soul>`, for the operator to qualify. → { souls } | null when neither key is set.
+ */
+export function soulsReplacement(local) {
+  const teams = isObject(local?.souls?.teams) ? local.souls.teams : null, defaults = isObject(local?.souls?.default) ? local.souls.default : null;
+  if (teams === null && defaults === null) return null;
+  const star = labelsOf(teams?.["*"]);
+  const souls = {};
+  if (star.length) souls["*"] = { teams: star };
+  const named = [...Object.keys(teams ?? {}), ...Object.keys(defaults ?? {})].filter((k, i, a) => k !== "*" && a.indexOf(k) === i);
+  for (const k of named) {
+    const def = str(defaults?.[k]);
+    const list = [...star, ...labelsOf(teams?.[k])].filter((l, i, a) => a.indexOf(l) === i);
+    souls[k.includes("/") ? k : `<member>/${k}`] = { ...(def !== null ? { default: def } : {}), teams: list };
+  }
+  return { souls };
+}
+
+/** Every discovered soul's key (teamKeyOf): confirmed members' (and a standalone view's own), external and
+ *  package souls. The typo guard (`team-soul-unknown`) checks the workspace's `souls:` keys against it. */
+export function discoveredTeamKeys(discovery) {
+  const keys = new Set();
+  for (const m of discovery?.members || []) if (m.confirmed || (discovery.standalone === true && m.key === discovery.key)) for (const s of m.souls || []) keys.add(teamKeyOf(s));
+  for (const x of discovery?.external || []) if (x?.soul) keys.add(teamKeyOf({ ...x.soul, repoKey: x.soul.repoKey ?? x.key }));
+  for (const s of discovery?.packageSouls || []) keys.add(teamKeyOf(s));
+  return keys;
+}
+
+/** The `souls:` patterns that apply to `key`, most specific first. */
+const patternsOf = (key) => (key === "*" ? ["*"] : [key, `${key.slice(0, key.lastIndexOf("/"))}/*`, "*"]);
 
 const unknown = (label, at) => fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared (${at}): declare it with \`oats teams add\`, or in oats-workspace.yaml teams: for a shared team`, { label, at });
+const closedMessage = (keys) => `${LOCAL_FILE} declares ${keys.join(", ")}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}`;
+/** Whether `e` refuses a soul's TEAMS (an undeclared label, or local teams the workspace does not allow):
+ *  readiness reports it as a team item, a home falls back to its recorded teams. */
+export const isTeamRefusal = (e) => e?.code === "E_TEAM_UNKNOWN" || (e?.code === "E_WORKSPACE_SCHEMA" && e?.details?.reason === "local-teams-closed");
+/** Whether `e` refuses oats-local.yaml for the team keys 0.38.0 removed (`souls.teams` / `souls.default`):
+ *  a reader that otherwise falls back to a home's recorded teams must answer it instead. */
+export const isRemovedTeamKeys = (e) => e?.code === "E_WORKSPACE_SCHEMA" && Array.isArray(e?.details?.problems)
+  && e.details.problems.some((p) => p?.reason === "removed-key" && /^\/souls\/(teams|default)$/.test(p.path));
+/** The refusal of local teams the workspace does not allow (E_WORKSPACE_SCHEMA reason local-teams-closed). */
+export const localTeamsClosed = (keys, { verb = null } = {}) => fail("E_WORKSPACE_SCHEMA",
+  verb ? `${verb} writes ${keys.join(", ")} in ${LOCAL_FILE}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}` : closedMessage(keys),
+  { reason: "local-teams-closed", path: LOCAL_FILE, keys: [...keys] });
 
 /**
- * One soul's teams here (key "*": the deployment default + souls.teams["*"]).
- * → { key, defaultTeam: DefaultTeam | null, teams: [TeamRow + via] } | throws E_TEAM_UNKNOWN / E_TEAM_NOT_ELIGIBLE.
- * `via` ⊂ ["default", "*", "soul"], in that order: why the soul has the team.
+ * One soul's teams here (key "*": what the "*" pattern gives).
+ * → { key, match, defaultMatch, defaultTeam: DefaultTeam | null, teams: [TeamRow] }; `match` / `defaultMatch`
+ * are the `souls:` keys its teams / its default come from (null: none). Throws E_WORKSPACE_SCHEMA
+ * (local-teams-closed) / E_TEAM_UNKNOWN.
  */
 export function soulTeams(model, key) {
-  const known = (label, at) => { if (!model.labels.has(label)) throw unknown(label, at); };
-  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
-  const star = labelsOf(model.souls.teams["*"]);
-  star.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/*/${i}`));
-  const own = key === "*" ? [] : labelsOf(model.souls.teams[key]);
-  own.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(key)}/${i}`));
-  const override = key === "*" ? null : str(model.souls.default[key]);
-  if (override !== null) {
-    const at = `${LOCAL_FILE}#/souls/default/${pointerKey(key)}`;
-    known(override, at);
-    if (override !== model.defaultTeam && !star.includes(override) && !own.includes(override)) {
-      throw fail("E_TEAM_NOT_ELIGIBLE", `souls.default.${key} is ${JSON.stringify(override)}, which is not one of ${key}'s teams here — add it first (\`oats soul teams ${key} --add ${override}\`)`, { soul: key, label: override, at });
-    }
-  }
-  const defaultLabel = override ?? model.defaultTeam;
+  if (model.closedKeys.length) throw localTeamsClosed(model.closedKeys);
+  const patterns = patternsOf(key);
+  const match = patterns.find((p) => isObject(model.souls[p])) ?? null;
+  const defaultMatch = patterns.find((p) => isObject(model.souls[p]) && typeof model.souls[p].default === "string") ?? null;
+  if (model.localDefault !== null && !model.labels.has(model.localDefault)) throw unknown(model.localDefault, `${LOCAL_FILE}#/defaultTeam`);
+  const [defaultLabel, from] = defaultMatch !== null ? [model.souls[defaultMatch].default, "soul"]
+    : model.localDefault !== null ? [model.localDefault, "deployment"]
+    : model.workspaceDefault !== null ? [model.workspaceDefault, "workspace"] : [null, null];
   const via = new Map();
-  const add = (label, why) => { const v = via.get(label) ?? []; if (!v.includes(why)) v.push(why); via.set(label, v); };
+  const add = (label, why) => { if (!model.labels.has(label)) return; const v = via.get(label) ?? []; if (!v.includes(why)) v.push(why); via.set(label, v); };
   if (defaultLabel !== null) add(defaultLabel, "default");
-  for (const l of star) add(l, "*");
-  for (const l of own) add(l, "soul");
+  const listed = match === null ? [] : model.souls[match].teams === "any" ? [...model.shared.keys()] : labelsOf(model.souls[match].teams);
+  for (const l of listed) add(l, "workspace");
+  if (model.localTeams !== false) for (const l of model.local.keys()) add(l, "local");
   const teams = [...via].map(([label, v]) => {
     const d = model.labels.get(label);
     return { label, team: d.team, default: label === defaultLabel, from: d.from, via: v };
   }).sort((a, b) => (b.default - a.default) || byCodepoint(a.label, b.label));
-  const defaultTeam = defaultLabel === null ? null : { label: defaultLabel, team: model.labels.get(defaultLabel).team, from: override !== null ? "soul" : "deployment" };
-  return { key, defaultTeam, teams };
+  const defaultTeam = defaultLabel === null || !model.labels.has(defaultLabel) ? null : { label: defaultLabel, team: model.labels.get(defaultLabel).team, from };
+  return { key, match, defaultMatch, defaultTeam, teams };
 }
 
-/** TeamRows as the reports carry them (unmapped included, no `via`). */
-export const reportRows = (teams) => (teams || []).map(({ label, team, default: d, from }) => ({ label, team, default: d, from }));
+/** TeamRows as the reports carry them (unmapped included). A row a home recorded before team model 3 has
+ *  no `via`, and is reported as recorded (its eligibility is not guessed). */
+export const reportRows = (teams) => (teams || []).map(({ label, team, default: d, from, via }) => ({ label, team, default: d, from, ...(Array.isArray(via) ? { via: [...via] } : {}) }));
 /** TeamRows as OATS_TEAMS and instance.json carry them: mapped only. */
 export const envRows = (teams) => reportRows(teams).filter((r) => r.team !== null);
 
 /** Every reference to `label` in oats-local.yaml, in written order (`oats teams remove` refuses on any). */
 export function teamReferences(model, label) {
-  const refs = [];
-  if (model.defaultTeam === label) refs.push("defaultTeam");
-  for (const [key, list] of Object.entries(model.souls.teams)) if (labelsOf(list).includes(label)) refs.push(`souls.teams:${key}`);
-  for (const [key, l] of Object.entries(model.souls.default)) if (l === label) refs.push(`souls.default:${key}`);
-  return refs;
+  return model.localDefault === label ? ["defaultTeam"] : [];
 }
 
 const collisionProblem = (label, shared, local) => ({
@@ -135,64 +190,48 @@ const collisionProblem = (label, shared, local) => ({
   message: `team ${label} is declared in both oats-workspace.yaml (shared) and oats-local.yaml (local); the shared definition wins`,
   fix: "rename the local label in oats-local.yaml",
 });
-const unmappedProblem = (d, isDefault) => isDefault
-  ? { code: "team-unmapped", label: d.label, default: true, severity: "failure", at: d.at, message: `the default team ${d.label} has no provider id yet`, fix: `${UNMAPPED_FIX}; or choose another default with \`oats teams default\`` }
+/** Where another default is chosen: where this one comes from (`t` is soulTeams' answer). */
+const otherDefault = (t) => t.defaultTeam?.from === "soul" ? `in the souls: entry ${t.defaultMatch} of oats-workspace.yaml`
+  : t.defaultTeam?.from === "workspace" ? "defaultTeam in oats-workspace.yaml" : "with `oats teams default`";
+const unmappedProblem = (d, t) => d.label === t.defaultTeam?.label
+  ? { code: "team-unmapped", label: d.label, default: true, severity: "failure", at: d.at, message: `the default team ${d.label} has no provider id yet`,
+    fix: `${UNMAPPED_FIX}; or choose another ${t.defaultTeam.from === "workspace" ? "" : "default "}${otherDefault(t)}` }
   : { code: "team-unmapped", label: d.label, default: false, severity: "warning", at: d.at, message: `shared team ${d.label} has no provider id yet`, fix: UNMAPPED_FIX };
-const unconfiguredProblem = () => ({ code: "E_TEAM_UNCONFIGURED", severity: "failure", message: "no teams configured: run `oats aweb setup`", fix: "run `oats aweb setup` (it creates the teams and sets the default), or `oats teams add <label> --team <id>`" });
+/** No default: committed in the workspace file, or recorded here where local teams are allowed (the standalone
+ *  view has only the local way). */
+const unconfiguredProblem = (model) => ({ code: "E_TEAM_UNCONFIGURED", severity: "failure", message: "no teams configured: run `oats aweb setup`",
+  fix: model.localTeams === null ? "run `oats aweb setup` (it creates the teams and sets the default), or `oats teams add <label> --team <id>`"
+    : `run \`oats aweb setup\` to create a team, then commit it in oats-workspace.yaml as defaultTeam (or as a soul's default in souls:)${model.localTeams ? ", or record it here with `oats teams add <label> --team <id>`" : ""}` });
 const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
-  fix: e.code === "E_TEAM_UNKNOWN" ? "declare the team (`oats teams add`), or remove the reference" : "add the label to the soul's teams (`oats soul teams … --add`), or clear its default (`--clear-default`)" });
-
-/** The fields of a team-model-3-migration problem other than code/severity/message/fix, as every
- *  surface (oats teams, readiness, doctor) carries them. */
-export const MIGRATION_CODE = "team-model-3-migration";
-/**
- * The team-model-3-migration warnings (0.36.x and 0.37.x; 0.38.0 refuses what they name): `local-soul-teams` when
- * oats-local.yaml has souls.teams / souls.default, `local-teams-closed` when it declares teams /
- * defaultTeam and the workspace file does not say `localTeams: true` (never without a workspace file).
- */
-export function migrationProblems(model) {
-  const m = model.migration, problems = [];
-  if (m.soulKeys.length) problems.push({ code: MIGRATION_CODE, severity: "warning", condition: "local-soul-teams", keys: [...m.soulKeys],
-    message: `oats-local.yaml ${m.soulKeys.join(", ")}: OATS 0.38.0 refuses ${m.soulKeys.length > 1 ? "these keys" : "this key"}; which teams a soul may join, and its default, move to souls: in oats-workspace.yaml`,
-    fix: `commit the same choices as souls: entries in oats-workspace.yaml ("*" or <member|package>/<soul>: { default, teams }), then remove ${m.soulKeys.join(" and ")} from oats-local.yaml` });
-  if (m.teamKeys.length && m.localTeams === false) problems.push(localTeamsClosedProblem(m.teamKeys));
-  return problems;
-}
-/** `local-teams-closed` for the oats-local.yaml `keys` found (doctor builds it from its offline read). */
-export const localTeamsClosedProblem = (keys) => ({ code: MIGRATION_CODE, severity: "warning", condition: "local-teams-closed", keys: [...keys],
-  message: `oats-local.yaml declares ${keys.join(", ")}, but oats-workspace.yaml does not say localTeams: true: OATS 0.38.0 refuses local teams and a local defaultTeam unless the workspace allows them`,
-  fix: "either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml" });
+  fix: "declare the team (`oats teams add`), or choose another default (`oats teams default`)" });
+const soulUnknownProblem = (key, at) => ({ code: "team-soul-unknown", severity: "warning", key, at,
+  message: `souls: ${key} names no soul of this workspace (a pattern is "*" or <member|package>/*)`, fix: "correct the key to a soul's qualified name (oats souls lists them), or remove it" });
+/** local-teams-closed as a problem (oats teams, readiness, doctor): the refusal's facts, never thrown. */
+export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA", severity: "failure", condition: "local-teams-closed", path: LOCAL_FILE, keys: [...keys],
+  message: closedMessage(keys), fix: CLOSED_FIX });
 
 /**
- * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared
- * teams (a failure when it is `defaultTeam`), every unknown reference, every ineligible
- * souls.default. With `key`: only what concerns that soul (`default` marks ITS default).
- * `messaging`: a messaging layer is active, so no default is E_TEAM_UNCONFIGURED.
+ * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared teams
+ * (a failure when it is the default a soul without a souls: default gets), an unknown local default.
+ * With `key`: only what concerns that soul (`default` marks ITS default). Local teams the workspace does
+ * not allow are the one problem either way. `messaging`: a messaging layer is active, so no default is
+ * E_TEAM_UNCONFIGURED. `soulKeys` (discoveredTeamKeys; null when the souls are not known): a `souls:` key
+ * that is neither a pattern nor one of them is `team-soul-unknown` (a typo guard, either way).
  */
-export function teamProblems(model, { key = null, messaging = false } = {}) {
+export function teamProblems(model, { key = null, messaging = false, soulKeys = null } = {}) {
+  if (model.closedKeys.length) return [localTeamsClosedProblem(model.closedKeys)];
   const problems = [];
-  if (key !== null) {
-    let t;
-    try { t = soulTeams(model, key); }
-    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e), ...migrationProblems(model)]; throw e; }
-    for (const r of t.teams) if (model.shared.has(r.label) && model.local.has(r.label)) problems.push(collisionProblem(r.label, model.shared.get(r.label), model.local.get(r.label)));
-    for (const r of t.teams) if (r.team === null) problems.push(unmappedProblem(model.labels.get(r.label), r.default));
-    if (messaging && t.defaultTeam === null) problems.push(unconfiguredProblem());
-    return [...problems, ...migrationProblems(model)];
-  }
-  const labels = [...model.labels.keys()].sort(byCodepoint);
+  // An undeclared local default is reported; the rest is judged as if it were not set.
+  if (model.localDefault !== null && !model.labels.has(model.localDefault)) problems.push(refusalProblem(unknown(model.localDefault, `${LOCAL_FILE}#/defaultTeam`)));
+  const t = soulTeams(problems.length ? { ...model, localDefault: null } : model, key ?? "*");
+  const labels = key !== null ? t.teams.map((r) => r.label) : [...model.labels.keys()].sort(byCodepoint);
   for (const label of labels) if (model.shared.has(label) && model.local.has(label)) problems.push(collisionProblem(label, model.shared.get(label), model.local.get(label)));
-  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, label === model.defaultTeam)); }
-  const known = (label, at) => { if (!model.labels.has(label)) problems.push(refusalProblem(unknown(label, at))); };
-  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
-  for (const [k, list] of Object.entries(model.souls.teams)) labelsOf(list).forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(k)}/${i}`));
-  for (const [k, l] of Object.entries(model.souls.default)) if (typeof l === "string") known(l, `${LOCAL_FILE}#/souls/default/${pointerKey(k)}`);
-  for (const [k, l] of Object.entries(model.souls.default)) {
-    if (typeof l !== "string" || !model.labels.has(l)) continue;
-    try { soulTeams(model, k); } catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE" && e.details.soul === k) problems.push(refusalProblem(e)); else if (e.code !== "E_TEAM_UNKNOWN") throw e; }
+  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, t)); }
+  if (messaging && t.defaultTeam === null && model.localDefault === null) problems.push(unconfiguredProblem(model));
+  if (soulKeys !== null) for (const k of Object.keys(model.souls).sort(byCodepoint)) {
+    if (k !== "*" && !k.endsWith("/*") && !soulKeys.has(k)) problems.push(soulUnknownProblem(k, `${model.soulsAt}/${pointerKey(k)}`));
   }
-  if (messaging && model.defaultTeam === null) problems.push(unconfiguredProblem());
-  return [...problems, ...migrationProblems(model)];
+  return problems;
 }
 
 /**

package/lib/workspace.mjs

@@ -18,7 +18,8 @@ import { oatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { bindRemote, classifyPackageValue, lockedPackageRef } from "./packages.mjs";
 import { manifestContractProblems } from "./capability-contract.mjs";
-import { BY_TEAM_REMOVED, TEAM_MEMBERSHIP_MOVED } from "./teams.mjs";
+import YAML from "yaml";
+import { BY_TEAM_REMOVED, TEAM_MEMBERSHIP_MOVED, soulsReplacement } from "./teams.mjs";
 
 /* ───────────────────────────── errors ─────────────────────────────────── */
 
@@ -261,7 +262,7 @@ function sharedLabelProblems(value, problems) {
 }
 export function validateMembership(value) { return withRemovedKeys(validateAgainst(schemaFor("membership"), value), value, REMOVED_KEYS.membership); }
 
-/** Keys 0.30 removed (team model v2): each is a schema problem naming its replacement, in place of
+/** Keys 0.30 (team model v2) and 0.38.0 (team model 3) removed: each is a schema problem naming its replacement, in place of
  *  the schema's generic "unexpected property". `at(value)` → the JSON pointers where it appears. */
 const REMOVED_KEYS = {
   workspace: [
@@ -270,6 +271,11 @@ const REMOVED_KEYS = {
   ],
   membership: [{ at: (v) => (isObject(v) && Object.hasOwn(v, "team") ? ["/team"] : []), message: TEAM_MEMBERSHIP_MOVED }],
   soul: [{ at: (v) => (isObject(v) && Object.hasOwn(v, "team") ? ["/team"] : []), message: TEAM_MEMBERSHIP_MOVED }],
+  // 0.38.0 (team model 3): a soul's teams and default are committed in the workspace's souls:.
+  local: [
+    { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "teams") ? ["/souls/teams"] : []), message: "souls.teams was removed in 0.38.0 (team model 3): which teams a soul may join is souls: in oats-workspace.yaml" },
+    { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "default") ? ["/souls/default"] : []), message: "souls.default was removed in 0.38.0 (team model 3): a soul's default team is souls: in oats-workspace.yaml (default:)" },
+  ],
 };
 function withRemovedKeys(problems, value, removed) {
   const found = removed.flatMap((r) => r.at(value).map((path) => ({ path, reason: "removed-key", message: r.message })));
@@ -316,7 +322,7 @@ function fromProblems(remote, capabilities, path, problems, { here }) {
 }
 /** Schema + domain problems for an oats-local.yaml value: settings[<cap>] may not carry the removed `byTeam` key. */
 export function validateLocal(value) {
-  const problems = validateAgainst(schemaFor("local"), value);
+  const problems = withRemovedKeys(validateAgainst(schemaFor("local"), value), value, REMOVED_KEYS.local);
   if (isObject(value) && isObject(value.settings)) for (const [cap, payload] of Object.entries(value.settings)) reservedKeyProblems(payload, `/settings/${pointerKey(cap)}`, problems);
   // runtime → harness (0.27.0, lead call 6): `runtime`, the pre-0.27 name, is still read; both,
   // disagreeing, are refused.
@@ -361,8 +367,12 @@ function schemaError(kind, origin, problems, value) {
   const where = origin.repoKey ? `${origin.repoKey}@${(origin.commit || "").slice(0, 12)}:${origin.path}` : origin.path;
   // A single-cause refusal (reserved-key, …) surfaces its reason on details for callers that branch on it.
   const reasons = new Set(problems.map((p) => p.reason).filter(Boolean));
-  return fail("E_WORKSPACE_SCHEMA", `${FILE_KINDS[kind].file} at ${where} is invalid${schemaHint(kind, value)}: ${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}`, {
-    path: origin.path, repoKey: origin.repoKey, commit: origin.commit, problems, ...(reasons.size === 1 ? { reason: [...reasons][0] } : {}),
+  // Team model 3: the refused souls.teams / souls.default come with the souls: that replaces them.
+  const moved = kind === "local" && problems.some((p) => p.reason === "removed-key" && /^\/souls\/(teams|default)$/.test(p.path)) ? soulsReplacement(value) : null;
+  const replacement = moved ? YAML.stringify(moved, { lineWidth: 0 }) : null;
+  return fail("E_WORKSPACE_SCHEMA", `${FILE_KINDS[kind].file} at ${where} is invalid${schemaHint(kind, value)}: ${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}`
+    + (replacement ? `; commit this in oats-workspace.yaml (<member> is the soul's member repository name, as souls.disabled names it), then remove souls.teams and souls.default from oats-local.yaml:\n${replacement}` : ""), {
+    path: origin.path, repoKey: origin.repoKey, commit: origin.commit, problems, ...(reasons.size === 1 ? { reason: [...reasons][0] } : {}), ...(replacement ? { replacement } : {}),
   });
 }
 

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.18.1",
+      "ref": "v1.20.0",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -33,7 +33,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.4.3",
+      "ref": "oats-framework/v1.5.0",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/skills/oats-getting-started/SKILL.md

@@ -60,7 +60,7 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.3                # bare versions resolve through the official catalog
+  oats.framework: v1.5.0                # bare versions resolve through the official catalog
   oats.okf: v4.1.1
 defaults:
   capabilities: { oats.core: { from: package } }
@@ -135,18 +135,29 @@ membership.
 ## 6. Give the deployment a team (with messaging)
 
 If a messaging capability fills the messaging slot, every instance lives in a
-team, and readiness fails with `E_TEAM_UNCONFIGURED` until this deployment has
-a default team. Create the team with the messaging provider (its own skills say
-how), then record it:
+team, and readiness fails with `E_TEAM_UNCONFIGURED` until there is a default
+team. Create the team with the messaging provider (its own skills say how),
+then commit it in `oats-workspace.yaml` with its provider id, and make it the
+default:
+
+```yaml
+teams:
+  research: { team: <provider team id> }
+defaultTeam: research
+```
+
+Push, then sync and check:
 
 ```bash
-oats teams add research --team <provider team id>   # a local team; the first one becomes the default
-oats teams
+oats sync --dir <dir>
+oats teams --dir <dir>
 ```
 
-A team the whole organisation uses is committed in `oats-workspace.yaml` as
-`teams.<label>` with its provider id; which souls join which team on this
-machine is `oats soul teams` (`/oats-teams`, in `oats.setup`).
+The teams an instance may join, and its default, are the organisation's
+decision, committed in this file: by default a soul joins its default team
+only, and `souls:` entries open other teams to a soul. A deployment declares
+teams of its own (`oats teams add`) only when the workspace says
+`localTeams: true` (`/oats-teams`, in `oats.setup`).
 
 ## 7. Spawn the first soul