hive-lite 0.1.6 → 0.1.8

package/README.md

@@ -74,9 +74,9 @@ node bin/hive.js next --agent codex --json
 `status` and `next` show actionable split notes by default: active split notes with accepted phase progress, or the newest unstarted split note when no active split exists. Use `status --all` to inspect every runtime split note. `next` may recommend start, finish, map maintenance, split continuation, dirty-worktree cleanup, or git repo setup. It does not run agents, commit, accept risk, or modify files.
 In JSON output, `splitNoteSummary.primaryRecentSplitNote` identifies the split note that `status`/`next` treat as primary, and `splitNoteSummary.otherActiveSplitNotes` lists older active split notes with accepted progress.
 
-When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`, `next` also checks whether the recommended Hive Lite operator skill is installed in that target. If it is missing or stale, `next` recommends installing/syncing skills before the handoff.
+When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`, `next` also checks whether the recommended Hive Lite operator skill is current in that target. If it is missing or stale, `next` recommends `skills sync` before the handoff.
 
-### Install Agent Skills
+### Sync Agent Skills
 
 Hive Lite ships four operator skills:
 
@@ -98,22 +98,22 @@ node bin/hive.js skills doctor --json
 
 Codex, Claude, and Gemini targets are global user-skill installs. `--agent codex` writes to `~/.codex/skills`, `--agent claude` writes to `~/.claude/skills`, and `--agent gemini` writes to `~/.gemini/skills`. They do not create or update repo-local `.codex/skills`, `.claude/skills`, or `.gemini/skills`. Use `--path <repo-local-skills-dir>` only when you intentionally want a custom repo-local copy that Hive Lite can inspect.
 
-Install missing skills:
+Install or update skills in one step:
 
 ```bash
-node bin/hive.js skills install --agent codex
-node bin/hive.js skills install --agent claude
-node bin/hive.js skills install --agent gemini
-node bin/hive.js skills install --agent all
+node bin/hive.js skills sync --agent codex
+node bin/hive.js skills sync --agent claude
+node bin/hive.js skills sync --agent gemini
+node bin/hive.js skills sync --agent all
 ```
 
-`install` creates missing skills but does not overwrite stale local copies unless `--force` is passed.
+`sync` installs missing skills and overwrites stale copies with the bundled version.
 
-Synchronize bundled skills over existing stale copies:
+`install` is still available for conservative installs that should not overwrite stale local copies unless `--force` is passed:
 
 ```bash
-node bin/hive.js skills sync --agent codex
-node bin/hive.js skills sync --agent all
+node bin/hive.js skills install --agent codex
+node bin/hive.js skills install --agent all
 ```
 
 Use `--dry-run` to preview writes. Use `--path <skills-dir>` for a custom target.

package/docs/skills/hive-lite-map-maintainer/references/lifecycle.md

@@ -56,7 +56,7 @@ Use when a real requirement hits a map gap during start:
 
 - `find.mode` is `needs_map` or `discovery_context`.
 - `find` selected a generic/broad area.
-- warnings include `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
+- warnings include `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_DIRECT_NEW_FILE_SCOPE`, `DIRECT_ONLY_REFERENCE_PEERS`, `BROAD_FALLBACK_ONLY`, `TARGET_ENTITY_MISMATCH`, `MISSING_ARTIFACT_FAMILY_SCOPE`, `MISSING_REQUIRED_HOOK_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
 - `map health --area <selected>` shows critical findings.
 
 Goal:

package/docs/skills/hive-lite-map-maintainer/references/repair-rules.md

@@ -55,6 +55,10 @@ Rules:
 
 - `readable` may be broad.
 - `writable_direct` should be exact existing files, usually 2-8 files.
+- Prefer `writable_existing` for exact update targets and `writable_create_patterns` for new file permissions when the repo has repeated artifact families.
+- For intents that create new peer files, use very small direct patterns that match only the expected family, such as `src/providers/*Provider.ts`; do not fall back to an entire source tree.
+- Existing peer files that are only copy/reference examples should stay readable/reference context, not selected Direct Writable for a new peer target.
+- Put peer examples under `readable_reference` and describe repeated families under `artifact_families` when possible.
 - Broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, and `**` must not be in `writable_direct`.
 - Every conditional/fallback item needs `reason` and `requires_review: true`.
 

package/docs/skills/hive-lite-start-prompt/SKILL.md

@@ -180,8 +180,9 @@ Accept the packet only when all are true:
 - `mode` is `edit_context`.
 - `area.id` is present.
 - `writableScope` contains at least one narrow direct file.
+- `writePlan.blockingWarnings` is empty when present.
 - `validationPlan` is not empty.
-- `warnings` has no map-gap warning such as `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
+- `warnings` has no map-gap warning such as `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_DIRECT_NEW_FILE_SCOPE`, `DIRECT_ONLY_REFERENCE_PEERS`, `BROAD_FALLBACK_ONLY`, `TARGET_ENTITY_MISMATCH`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
 - `hive-lite map health --area <areaId> --json` reports no critical findings.
 
 Review-gated conditional or broad fallback scope is allowed. Include it in the final prompt as a boundary, not as a failure.
@@ -200,7 +201,12 @@ Repair principles:
 
 - Prefer focused product/work area ids such as `dashboard.action_inbox`, not one-part ids such as `dashboard`.
 - Preserve unrelated areas exactly unless a change is needed for the reported map gap.
-- Use `scope.writable_direct` for exact files the coding agent may edit.
+- Use `scope.writable_direct` for exact files the coding agent may edit, or very small direct patterns when the intent needs new peer files such as a provider, proxy, adapter, connector, or plugin.
+- Prefer `scope.writable_existing` for exact update targets and `scope.writable_create_patterns` for narrow create permissions when the map needs operation-specific write capabilities.
+- Put copy sources and peer examples under `scope.readable_reference` when they should guide implementation but not be edited.
+- Use `artifact_families` to declare required create artifacts and hook files for repeated artifact families such as providers, adapters, connectors, endpoints, DTOs, tests, or migrations.
+- Treat Direct Writable as the selected intent-specific write target list, not the area's full writable maximum.
+- Keep peer examples, entrypoints, and similar existing files as reference context unless the current intent specifically requires editing them.
 - Put conditional files under `scope.writable_conditional` with `reason` and `requires_review: true`.
 - Put broad patterns only under `scope.writable_broad_fallback` with `reason` and `requires_review: true`.
 - Never put broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, or `**` in `writable_direct`.
@@ -270,6 +276,9 @@ Use this context packet as your source of truth. Edit only Direct Writable files
 Direct Writable:
 - <file>
 
+Reference Files:
+- <file and reason, only when useful; do not edit unless it is also Direct Writable>
+
 Review-Gated:
 - <conditional/broad item and reason>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/src/cli.js

@@ -230,6 +230,22 @@ function printContext(result) {
       console.log(`    risk: ${item.risk}`);
     }
   }
+  if (packet.writePlan && packet.writePlan.hypotheses && packet.writePlan.hypotheses.length > 0) {
+    console.log('');
+    console.log('Write Plan:');
+    for (const item of packet.writePlan.hypotheses) {
+      console.log(`  - ${item.action} ${item.artifactFamily}: ${item.operation}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''}`);
+    }
+    if (packet.writePlan.blockingWarnings && packet.writePlan.blockingWarnings.length > 0) {
+      console.log('  blocking:');
+      for (const item of packet.writePlan.blockingWarnings) console.log(`    - ${item.code}: ${item.message}`);
+    }
+  }
+  if (packet.writePlan && packet.writePlan.referenceFiles && packet.writePlan.referenceFiles.length > 0) {
+    console.log('');
+    console.log('Reference Files:');
+    for (const file of packet.writePlan.referenceFiles) console.log(`  - ${file.path}\n    reason: ${file.reason}`);
+  }
   console.log('');
   console.log('Relevant Files:');
   if (packet.relevantFiles.length === 0) console.log('  - (none found)');
@@ -242,6 +258,14 @@ function printContext(result) {
     console.log('');
     console.log(`Scope Quality: ${packet.scope.quality}`);
     console.log('');
+    console.log('Writable Existing Scope:');
+    if (!packet.scope.writableExisting || packet.scope.writableExisting.length === 0) console.log('  - (none configured)');
+    for (const item of packet.scope.writableExisting || []) console.log(`  - ${patternDisplay(item)}`);
+    console.log('');
+    console.log('Writable Create Patterns:');
+    if (!packet.scope.writableCreatePatterns || packet.scope.writableCreatePatterns.length === 0) console.log('  - (none configured)');
+    for (const item of packet.scope.writableCreatePatterns || []) console.log(`  - ${patternDisplay(item)}`);
+    console.log('');
     console.log('Conditional Writable Scope:');
     if (packet.scope.writableConditional.length === 0) console.log('  - (none configured)');
     for (const item of packet.scope.writableConditional) console.log(`  - ${patternDisplay(item)}`);
@@ -363,6 +387,24 @@ function printCheck(root, result) {
     console.log('  broad fallback:');
     for (const item of change.scope.writableBroadFallback) console.log(`    - ${patternDisplay(item)}`);
   }
+  if (change.writePlanStatus) {
+    console.log('');
+    console.log('Write Plan:');
+    console.log(`  ${change.writePlanStatus.status}`);
+    if (change.writePlanStatus.contextMode) console.log(`  context mode: ${change.writePlanStatus.contextMode}`);
+    if (change.writePlanStatus.selectedWritableDirect && change.writePlanStatus.selectedWritableDirect.length > 0) {
+      console.log('  selected direct:');
+      for (const item of change.writePlanStatus.selectedWritableDirect) console.log(`    - ${item}`);
+    }
+    if (change.writePlanStatus.referenceOnlyTouched && change.writePlanStatus.referenceOnlyTouched.length > 0) {
+      console.log('  reference-only touched:');
+      for (const item of change.writePlanStatus.referenceOnlyTouched) console.log(`    - ${item.path}: ${item.reason || item.reference}`);
+    }
+    if (change.writePlanStatus.blockingReasons && change.writePlanStatus.blockingReasons.length > 0) {
+      console.log('  blockers:');
+      for (const reason of change.writePlanStatus.blockingReasons) console.log(`    - ${reason}`);
+    }
+  }
   console.log('');
   console.log('Validation:');
   console.log(`  ${change.validation.status}`);

package/src/lib/change.js

@@ -174,9 +174,15 @@ function scopeFromContext(root, context) {
     });
   }
   const scope = context.scope;
+  const selectedDirect = Array.isArray(context.writableScope) && context.writableScope.length > 0
+    ? context.writableScope
+    : (scope.writableDirect || []);
   return {
     readable: (scope.readable || []).slice(),
-    writableDirect: (scope.writableDirect || []).map(itemPattern).filter(Boolean),
+    readableReference: (scope.readableReference || []).slice(),
+    writableDirect: selectedDirect.map(itemPattern).filter(Boolean),
+    writableExisting: normalizePatternList(scope.writableExisting || [], { source: 'writable_existing' }),
+    writableCreatePatterns: normalizePatternList(scope.writableCreatePatterns || [], { source: 'writable_create_patterns' }),
     writableConditional: normalizePatternList(scope.writableConditional || [], { requiresReview: true }),
     writableBroadFallback: normalizePatternList(scope.writableBroadFallback || [], { requiresReview: true }),
     forbidden: (scope.forbidden || []).slice(),
@@ -190,6 +196,9 @@ function firstItemMatch(file, items) {
 
 function scopeCheck(root, files, context, map) {
   const filePaths = files.map((item) => item.path || item);
+  const referenceOnly = context && context.writePlan && Array.isArray(context.writePlan.referenceFiles)
+    ? context.writePlan.referenceFiles.map((item) => item.path || item.pattern).filter(Boolean)
+    : [];
   const matchedAreas = [];
   let scope = {
     readable: [],
@@ -236,6 +245,13 @@ function scopeCheck(root, files, context, map) {
       violations.push(`${file} matched doNotTouch ${forbidden}`);
       continue;
     }
+    const reference = firstPatternMatch(file, referenceOnly);
+    if (reference) {
+      matchedTiers.unmatched.push(file);
+      review.push(file);
+      reviewDetails.push(`${file} matched reference-only file ${reference}`);
+      continue;
+    }
     const direct = firstItemMatch(file, scope.writableDirect);
     if (direct) {
       matchedTiers.direct.push(file);
@@ -298,6 +314,63 @@ function validationPlanFromContextOrMap(context, map) {
   }] : [];
 }
 
+function evaluateWritePlanStatus(files, context) {
+  if (!context) {
+    return {
+      status: 'not_available',
+      contextMode: null,
+      blockingReasons: [],
+      selectedWritableDirect: [],
+      referenceOnlyTouched: [],
+      requiredWrites: [],
+      blockingWarnings: [],
+    };
+  }
+
+  const writePlan = context.writePlan || null;
+  const blockingWarnings = writePlan && Array.isArray(writePlan.blockingWarnings)
+    ? writePlan.blockingWarnings
+    : [];
+  const selectedWritableDirect = Array.isArray(context.writableScope) ? context.writableScope : [];
+  const changedPaths = files.map((item) => item.path || item);
+  const referenceFiles = writePlan && Array.isArray(writePlan.referenceFiles) ? writePlan.referenceFiles : [];
+  const referenceOnlyTouched = [];
+  for (const file of changedPaths) {
+    const reference = referenceFiles.find((item) => matchesPattern(file, item.path || item.pattern));
+    if (reference) {
+      referenceOnlyTouched.push({
+        path: file,
+        reference: reference.path || reference.pattern,
+        reason: reference.reason || '',
+      });
+    }
+  }
+
+  const blockingReasons = [];
+  if (context.mode && context.mode !== 'edit_context') {
+    blockingReasons.push(`context mode is ${context.mode}, not edit_context`);
+  }
+  for (const warning of blockingWarnings) {
+    blockingReasons.push(`${warning.code}: ${warning.message}`);
+  }
+  for (const item of referenceOnlyTouched) {
+    blockingReasons.push(`${item.path} touched reference-only file ${item.reference}`);
+  }
+  if (selectedWritableDirect.length === 0 && changedPaths.length > 0) {
+    blockingReasons.push('context has no selected Direct Writable scope');
+  }
+
+  return {
+    status: blockingReasons.length > 0 ? 'blocked' : 'clean',
+    contextMode: context.mode || null,
+    blockingReasons: [...new Set(blockingReasons)],
+    selectedWritableDirect,
+    referenceOnlyTouched,
+    requiredWrites: writePlan && Array.isArray(writePlan.hypotheses) ? writePlan.hypotheses : [],
+    blockingWarnings,
+  };
+}
+
 function createOrUpdateChange(cwd, options = {}) {
   const root = repoRoot(cwd);
   const map = loadProjectMap(root);
@@ -339,6 +412,7 @@ function createOrUpdateChange(cwd, options = {}) {
       text: diffText,
     },
     scope: scopeCheck(root, files, context, map),
+    writePlanStatus: evaluateWritePlanStatus(files, context),
     validation: {
       status: existing && existing.validation ? existing.validation.status : 'not_run',
       plan: validationPlanFromContextOrMap(context, map),

package/src/lib/context.js

@@ -40,6 +40,374 @@ function tokenize(value) {
   return [...new Set([...latin, ...cjk])];
 }
 
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function looksLikeFilePattern(pattern) {
+  if (String(pattern || '').includes('*')) return false;
+  const base = path.basename(String(pattern || ''));
+  return /\.[A-Za-z0-9]+$/.test(base);
+}
+
+function isCreateCapablePattern(pattern) {
+  return !looksLikeFilePattern(pattern);
+}
+
+const IDENTITY_ALIASES = {
+  openai: ['openai', 'chatgpt', 'gpt'],
+  google: ['google', 'gemini'],
+  qwen: ['qwen', 'tongyi'],
+  wan: ['wan'],
+  aliyun: ['aliyun', 'ali'],
+  anthropic: ['anthropic', 'claude'],
+  azure: ['azure'],
+};
+
+function canonicalIdentity(value) {
+  const text = normalize(value);
+  if (!text) return null;
+  for (const [canonical, aliases] of Object.entries(IDENTITY_ALIASES)) {
+    if (aliases.includes(text)) return canonical;
+  }
+  return text;
+}
+
+function targetIdentityForIntent(intent) {
+  const tokens = tokenize(intent);
+  for (const token of tokens) {
+    const identity = canonicalIdentity(token);
+    if (identity && Object.prototype.hasOwnProperty.call(IDENTITY_ALIASES, identity)) return identity;
+  }
+  return null;
+}
+
+function peerIdentityFromPath(pattern) {
+  if (!looksLikeFilePattern(pattern)) return null;
+  const tokens = basenameTokens(pattern);
+  for (const token of tokens) {
+    const identity = canonicalIdentity(token);
+    if (identity && Object.prototype.hasOwnProperty.call(IDENTITY_ALIASES, identity)) return identity;
+  }
+  return null;
+}
+
+function identityMatches(left, right) {
+  if (!left || !right) return false;
+  return canonicalIdentity(left) === canonicalIdentity(right);
+}
+
+function intentTargetsAllPeers(intent) {
+  const text = normalize(intent);
+  return [
+    /\b(all|every|each)\b/,
+    /所有|全部|每个|统一|全量|全部/,
+  ].some((pattern) => pattern.test(text));
+}
+
+function arrayFrom(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '')).filter(Boolean);
+  if (value == null || value === '') return [];
+  if (typeof value === 'object') return [];
+  return [String(value)];
+}
+
+function configuredArtifactFamilies(area) {
+  const raw = area && area.artifact_families ? area.artifact_families : null;
+  if (!raw) return [];
+  if (Array.isArray(raw)) {
+    return raw.map((item) => ({
+      id: item.id || item.name || '',
+      triggerTerms: [
+        ...arrayFrom(item.trigger_terms || item.triggerTerms),
+        ...arrayFrom(item.trigger_terms && item.trigger_terms.en),
+        ...arrayFrom(item.trigger_terms && item.trigger_terms.zh),
+      ],
+      createRequires: arrayFrom(item.create_requires || item.createRequires),
+      hooks: arrayFrom(item.hooks),
+      examples: arrayFrom(item.examples),
+    })).filter((item) => item.id);
+  }
+  return Object.entries(raw).map(([id, value]) => ({
+    id,
+    triggerTerms: [
+      ...arrayFrom(value && (value.trigger_terms || value.triggerTerms)),
+      ...arrayFrom(value && value.trigger_terms && value.trigger_terms.en),
+      ...arrayFrom(value && value.trigger_terms && value.trigger_terms.zh),
+    ],
+    createRequires: arrayFrom(value && (value.create_requires || value.createRequires)),
+    hooks: arrayFrom(value && value.hooks),
+    examples: arrayFrom(value && value.examples),
+  }));
+}
+
+function configuredArtifactFamilyForIntent(area, intent) {
+  const text = normalize(intent);
+  for (const family of configuredArtifactFamilies(area)) {
+    const terms = unique([
+      family.id,
+      ...family.triggerTerms,
+    ]).map(normalize).filter(Boolean);
+    if (terms.some((term) => text.includes(term))) return family;
+  }
+  return null;
+}
+
+function classifyArtifactFamily(intent, area) {
+  const configured = configuredArtifactFamilyForIntent(area, intent);
+  if (configured) return configured.id;
+  const text = normalize(intent);
+  if ([
+    /\b(provider|proxy|adapter|integration|connector|plugin)\b/,
+    /代理|提供商|适配器|集成|连接器|插件/,
+  ].some((pattern) => pattern.test(text))) return 'provider_proxy';
+  if ([
+    /\b(endpoint|controller|route|api)\b/,
+    /接口|端点|路由|控制器/,
+  ].some((pattern) => pattern.test(text))) return 'endpoint';
+  if ([
+    /\b(dto|request|response|payload)\b/,
+    /请求|响应|入参|出参/,
+  ].some((pattern) => pattern.test(text))) return 'dto';
+  if ([
+    /\b(migration|database|db|sql)\b/,
+    /数据库|迁移|表结构/,
+  ].some((pattern) => pattern.test(text))) return 'migration';
+  if ([
+    /\b(test|spec)\b/,
+    /测试|用例/,
+  ].some((pattern) => pattern.test(text))) return 'test';
+  if ([
+    /\b(component|page|view|ui)\b/,
+    /组件|页面|视图|界面/,
+  ].some((pattern) => pattern.test(text))) return 'component';
+  if ([
+    /\b(service)\b/,
+    /服务/,
+  ].some((pattern) => pattern.test(text))) return 'service';
+  return 'unknown';
+}
+
+function classifyIntentWrite(intent, area) {
+  const text = normalize(intent);
+  const createTerm = [
+    /\b(add|create|new|introduce|support|implement)\b/,
+    /新增|新建|创建|添加|接入|支持/,
+  ].some((pattern) => pattern.test(text));
+  const deleteTerm = [
+    /\b(delete|remove)\b/,
+    /删除|移除/,
+  ].some((pattern) => pattern.test(text));
+  const renameTerm = [
+    /\b(rename|move)\b/,
+    /重命名|改名|迁移/,
+  ].some((pattern) => pattern.test(text));
+  const targetAll = intentTargetsAllPeers(intent);
+  const artifactFamily = classifyArtifactFamily(intent, area);
+  const familyConfig = configuredArtifactFamilies(area).find((item) => item.id === artifactFamily) || null;
+  const targetIdentity = targetIdentityForIntent(intent);
+  let action = 'modify';
+  if (deleteTerm) action = 'delete';
+  else if (renameTerm) action = 'rename';
+  else if (createTerm && !targetAll) action = 'create';
+  return {
+    action,
+    artifactFamily,
+    targetIdentity,
+    operation: action === 'create' && artifactFamily === 'provider_proxy' ? 'create_file' : 'modify_existing_file',
+    required: true,
+    targetAll,
+    intentKind: action === 'create' ? `add_${artifactFamily}` : `${action}_${artifactFamily}`,
+    createRequires: familyConfig ? familyConfig.createRequires : [],
+    hooks: familyConfig ? familyConfig.hooks : [],
+    confidence: artifactFamily === 'unknown' ? 'low' : 'medium',
+  };
+}
+
+function directCapabilities(scope) {
+  const explicitItems = [
+    ...(scope.writableDirectItems || []),
+  ];
+  const items = explicitItems.length
+    ? explicitItems
+    : (scope.writableDirect || []).map((pattern) => ({ pattern, source: 'writable_direct' }));
+  const seen = new Set();
+  return items.map((item) => {
+    const pattern = item.pattern || item.path || item;
+    const createCapable = isCreateCapablePattern(pattern);
+    const configuredOperations = arrayFrom(item.operations);
+    const operations = configuredOperations.length
+      ? configuredOperations
+      : (createCapable ? ['update_existing', 'create_file'] : ['update_existing']);
+    const key = `${pattern}:${operations.join(',')}:${item.source || ''}:${item.artifact || ''}`;
+    if (seen.has(key)) return null;
+    seen.add(key);
+    return {
+      scope: pattern,
+      operations,
+      breadth: createCapable ? 'narrow_pattern' : 'exact',
+      reviewGated: false,
+      source: item.source || 'writable_direct',
+      artifact: item.artifact || null,
+      artifactFamily: item.artifactFamily || item.artifact_family || null,
+      intentKinds: arrayFrom(item.intentKinds || item.intent_kinds),
+      requiredWhen: arrayFrom(item.requiredWhen || item.required_when),
+      targetSlot: item.targetSlot || item.target_slot || null,
+      peerIdentity: canonicalIdentity(item.targetIdentity || item.target_identity || item.peerIdentity || item.peer_identity) || peerIdentityFromPath(pattern),
+    };
+  }).filter(Boolean);
+}
+
+function warning(code, message, data = {}) {
+  return {
+    code,
+    message,
+    blocking: data.blocking !== false,
+    ...data,
+  };
+}
+
+function buildReference(capability, reason) {
+  return {
+    path: capability.scope || capability.path,
+    role: capability.role || 'peer_example',
+    writable: false,
+    reason,
+    artifact: capability.artifact || null,
+    peerIdentity: capability.peerIdentity || null,
+  };
+}
+
+function artifactMatches(capability, artifact) {
+  if (!artifact) return false;
+  return capability.artifact === artifact || capability.artifactFamily === artifact;
+}
+
+function capabilityMatchesIntent(capability, hypothesis) {
+  if (!capability.intentKinds || capability.intentKinds.length === 0) return true;
+  return capability.intentKinds.includes(hypothesis.intentKind);
+}
+
+function buildWritePlan(scope, intent, area) {
+  const hypothesis = classifyIntentWrite(intent, area);
+  const capabilities = directCapabilities(scope);
+  const warnings = [];
+  const references = (scope.readableReference || []).map((item) => buildReference(
+    {
+      path: item.path,
+      role: item.role || 'reference',
+      artifact: item.artifact || null,
+      peerIdentity: canonicalIdentity(item.peerIdentity) || peerIdentityFromPath(item.path),
+    },
+    item.reason || 'readable reference from Project Map'
+  ));
+  let selected = capabilities.map((item) => item.scope);
+
+  if (hypothesis.operation === 'create_file' && hypothesis.artifactFamily === 'provider_proxy') {
+    const createCapabilities = capabilities.filter((item) => (
+      item.operations.includes('create_file') && capabilityMatchesIntent(item, hypothesis)
+    ));
+    const genericExistingCapabilities = capabilities.filter((item) => (
+      !item.peerIdentity && !item.operations.includes('create_file')
+    ));
+    const referencePeers = capabilities.filter((item) => (
+      item.peerIdentity
+      && hypothesis.targetIdentity
+      && !identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+    ));
+    const selectedCreateCapabilities = hypothesis.createRequires.length
+      ? createCapabilities.filter((item) => hypothesis.createRequires.some((artifact) => artifactMatches(item, artifact)))
+      : createCapabilities;
+    const hookCapabilities = hypothesis.hooks.length
+      ? genericExistingCapabilities.filter((item) => hypothesis.hooks.some((artifact) => artifactMatches(item, artifact)))
+      : genericExistingCapabilities;
+
+    selected = selectedCreateCapabilities.length > 0
+      ? [...selectedCreateCapabilities, ...hookCapabilities].map((item) => item.scope)
+      : [];
+    for (const capability of referencePeers) {
+      references.push(buildReference(
+        capability,
+        `peer identity ${capability.peerIdentity} differs from target ${hypothesis.targetIdentity}; use as a reference example only`
+      ));
+    }
+
+    if (createCapabilities.length === 0) {
+      warnings.push(warning(
+        'MISSING_DIRECT_NEW_FILE_SCOPE',
+        'Intent appears to add a new peer provider/proxy artifact, but direct writable scope does not include a narrow create pattern.'
+      ));
+    }
+    for (const artifact of hypothesis.createRequires) {
+      if (!createCapabilities.some((item) => artifactMatches(item, artifact))) {
+        warnings.push(warning(
+          'MISSING_ARTIFACT_FAMILY_SCOPE',
+          `Intent requires provider/proxy artifact ${artifact}, but no direct create capability covers it.`,
+          { artifact }
+        ));
+      }
+    }
+    for (const artifact of hypothesis.hooks) {
+      if (!genericExistingCapabilities.some((item) => artifactMatches(item, artifact))) {
+        warnings.push(warning(
+          'MISSING_REQUIRED_HOOK_SCOPE',
+          `Intent requires provider/proxy hook ${artifact}, but no direct existing-file capability covers it.`,
+          { artifact }
+        ));
+      }
+    }
+    if (referencePeers.length > 0 && createCapabilities.length === 0) {
+      warnings.push(warning(
+        'DIRECT_ONLY_REFERENCE_PEERS',
+        'Direct writable scope only contains existing peer provider/proxy files for other identities; those are reference examples, not the target write files.'
+      ));
+    }
+    if (createCapabilities.length === 0 && (scope.writableBroadFallback || []).length > 0) {
+      warnings.push(warning(
+        'BROAD_FALLBACK_ONLY',
+        'Only broad fallback scope appears able to cover new provider/proxy files; broad fallback is review-gated and is not direct write permission.'
+      ));
+    }
+  } else if (
+    hypothesis.artifactFamily === 'provider_proxy'
+    && hypothesis.targetIdentity
+    && !hypothesis.targetAll
+  ) {
+    const targetMatches = capabilities.filter((item) => (
+      item.peerIdentity && identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+    ));
+    const genericCapabilities = capabilities.filter((item) => (
+      !item.peerIdentity && !item.operations.includes('create_file')
+    ));
+    const referencePeers = capabilities.filter((item) => (
+      item.peerIdentity && !identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+    ));
+    selected = unique([...targetMatches, ...genericCapabilities].map((item) => item.scope));
+    for (const capability of referencePeers) {
+      references.push(buildReference(
+        capability,
+        `peer identity ${capability.peerIdentity} differs from target ${hypothesis.targetIdentity}`
+      ));
+    }
+    if (targetMatches.length === 0 && referencePeers.length > 0) {
+      warnings.push(warning(
+        'TARGET_ENTITY_MISMATCH',
+        `Intent targets ${hypothesis.targetIdentity}, but direct writable peer files are for other identities.`
+      ));
+    }
+  }
+
+  selected = unique(selected);
+  return {
+    hypotheses: [hypothesis],
+    capabilities,
+    selectedWritableDirect: selected,
+    referenceFiles: references,
+    blockingWarnings: warnings.filter((item) => item.blocking !== false),
+    warnings,
+  };
+}
+
 function basenameTokens(file) {
   return tokenize(path.basename(file || '').replace(/([a-z])([A-Z])/g, '$1 $2'));
 }
@@ -734,10 +1102,22 @@ function reviewGatedNotices(scope) {
   return notices;
 }
 
-function contextMode(area, scope, validationPlan, relevant, decomposition = []) {
+function hasBlockingMapGapWarning(warnings = []) {
+  return warnings.some((warning) => warning.blocking === true || [
+    'MISSING_DIRECT_NEW_FILE_SCOPE',
+    'DIRECT_ONLY_REFERENCE_PEERS',
+    'BROAD_FALLBACK_ONLY',
+    'TARGET_ENTITY_MISMATCH',
+    'MISSING_ARTIFACT_FAMILY_SCOPE',
+    'MISSING_REQUIRED_HOOK_SCOPE',
+  ].includes(warning.code));
+}
+
+function contextMode(area, selectedWritableDirect, validationPlan, relevant, decomposition = [], warnings = []) {
   if (!area) return 'needs_map';
+  if (selectedWritableDirect.length === 0) return 'discovery_context';
+  if (hasBlockingMapGapWarning(warnings)) return 'discovery_context';
   if (decomposition.some((item) => item.blocking)) return 'needs_decomposition';
-  if (scope.writableDirect.length === 0) return 'discovery_context';
   if (relevant.length === 0 || !relevant.some((file) => file.source === 'project_map')) return 'discovery_context';
   if (validationPlan.length === 0) return 'discovery_context';
   return 'edit_context';
@@ -850,12 +1230,31 @@ function buildContextMarkdown(packet) {
       ...packet.phaseDependencyStatus.missingRequiredAcceptedPhases.map((item) => `- Missing required phase: ${item}`),
       '',
     ] : []),
+    ...(packet.writePlan ? [
+      '## Write Plan',
+      ...packet.writePlan.hypotheses.map((item) => `- ${item.action} ${item.artifactFamily}: ${item.operation}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''}`),
+      ...(packet.writePlan.blockingWarnings.length
+        ? packet.writePlan.blockingWarnings.map((item) => `- Blocking: ${item.code}: ${item.message}`)
+        : ['- Coverage: direct writable scope covers the inferred write operation.']),
+      '',
+    ] : []),
+    ...(packet.writePlan && packet.writePlan.referenceFiles.length ? [
+      '## Reference Files',
+      ...packet.writePlan.referenceFiles.map((file) => `- ${file.path}: ${file.reason}`),
+      '',
+    ] : []),
     '## Relevant Files',
     ...packet.relevantFiles.map((file) => `- ${file.path} (${file.role || file.source}): ${file.reason}`),
     '',
     '## Writable Scope',
     ...(packet.writableScope.length ? packet.writableScope.map((item) => `- ${item}`) : ['- (none; this is not an edit permit)']),
     '',
+    '## Writable Existing Scope',
+    ...(packet.scope.writableExisting && packet.scope.writableExisting.length ? packet.scope.writableExisting.map((item) => `- ${patternDisplay(item)}`) : ['- (none configured)']),
+    '',
+    '## Writable Create Patterns',
+    ...(packet.scope.writableCreatePatterns && packet.scope.writableCreatePatterns.length ? packet.scope.writableCreatePatterns.map((item) => `- ${patternDisplay(item)}`) : ['- (none configured)']),
+    '',
     '## Conditional Writable Scope',
     ...(packet.scope.writableConditional.length ? packet.scope.writableConditional.map((item) => `- ${patternDisplay(item)}`) : ['- (none configured)']),
     '',
@@ -921,12 +1320,24 @@ function createContextPacket(root, intent, options = {}) {
   const candidateAreas = candidateAreasFromScored(scored);
   const scope = area ? normalizeAreaScope(root, area) : {
     readable: [],
+    readableReference: [],
     writableDirect: [],
+    writableDirectItems: [],
+    writableExisting: [],
+    writableCreatePatterns: [],
     writableConditional: [],
     writableBroadFallback: [],
     forbidden: [],
     quality: 'unknown',
   };
+  const writePlan = area ? buildWritePlan(scope, intent, area) : {
+    hypotheses: [],
+    capabilities: [],
+    selectedWritableDirect: [],
+    referenceFiles: [],
+    blockingWarnings: [],
+    warnings: [],
+  };
   const restrictGrepToReadable = area && (confidence === 'high' || findOptions.area) && scope.readable.length > 0;
   const grepFiles = grepHints(root, tokens, maxFiles, {
     allowedPatterns: restrictGrepToReadable ? scope.readable : [],
@@ -969,6 +1380,7 @@ function createContextPacket(root, intent, options = {}) {
     });
   } else {
     warnings.push(...scopeWarnings(scope));
+    warnings.push(...writePlan.warnings);
     if (relevant.length === 0 || !relevant.some((file) => file.source === 'project_map')) {
       warnings.push({
         code: 'MISSING_ENTRYPOINT',
@@ -984,7 +1396,7 @@ function createContextPacket(root, intent, options = {}) {
   }
   const reviewGated = area ? reviewGatedNotices(scope) : [];
   warnings.push(...splitRoutingWarnings(originSplit, phaseStatus, originPhaseAreaId, requestedArea));
-  const decomposition = decompositionSignals({
+  const rawDecomposition = decompositionSignals({
     map,
     area,
     confidence,
@@ -995,8 +1407,9 @@ function createContextPacket(root, intent, options = {}) {
     validationPlan,
     constrainedAreaId,
   });
+  const decomposition = hasBlockingMapGapWarning(warnings) ? [] : rawDecomposition;
   const phaseSeeds = decomposition.length > 0 ? candidatePhaseSeeds(scored, intent) : [];
-  let mode = contextMode(area, scope, validationPlan, relevant, decomposition);
+  let mode = contextMode(area, writePlan.selectedWritableDirect, validationPlan, relevant, decomposition, warnings);
   if (missingSplitReference(phaseStatus) && mode === 'edit_context') mode = 'discovery_context';
   const actions = recommendedActions(mode, intent, id, phaseStatus);
   const packet = {
@@ -1034,7 +1447,8 @@ function createContextPacket(root, intent, options = {}) {
     phaseDependencyStatus: phaseStatus,
     relevantFiles: relevant,
     scope,
-    writableScope: scope.writableDirect.slice(),
+    writePlan,
+    writableScope: writePlan.selectedWritableDirect.slice(),
     readableScope: scope.readable.slice(),
     doNotTouch: scope.forbidden.slice(),
     validationPlan,
@@ -1076,6 +1490,7 @@ function createContextPacket(root, intent, options = {}) {
       })),
       validationQuality: validationPlan.length > 0 ? 'configured' : 'missing',
       warnings,
+      writePlan,
       reviewGated,
       decompositionSignals: decomposition,
       candidatePhaseSeeds: phaseSeeds,

package/src/lib/evidence.js

@@ -106,6 +106,13 @@ function evaluateEvidencePolicy(change, map) {
   let changeClass = 'unknown';
   let verdict = 'acceptable';
 
+  if (change.writePlanStatus && change.writePlanStatus.status === 'blocked') {
+    verdict = 'blocked';
+    missing.push('write_plan_clean');
+    required.push('write_plan_clean');
+    reasons.push(...(change.writePlanStatus.blockingReasons || []).map((item) => `Write plan blocked: ${item}`));
+  }
+
   if (change.scope.status === 'violation') {
     verdict = 'blocked';
     missing.push('scope_clean');

package/src/lib/map.js

@@ -331,10 +331,14 @@ function summarizeFindContext(context) {
     },
     warnings: context.warnings || [],
     reviewGated: context.reviewGated || (context.explain && context.explain.reviewGated) || [],
+    writePlan: context.writePlan || (context.explain && context.explain.writePlan) || null,
     candidateAreas: context.candidateAreas || [],
     areaScores: context.explain && context.explain.areaScores ? context.explain.areaScores : [],
     scopeQuality: scope.quality || (context.explain ? context.explain.scopeQuality : 'unknown'),
     writableDirect: scope.writableDirect || context.writableScope || [],
+    selectedWritableScope: context.writableScope || [],
+    writableExisting: scope.writableExisting || [],
+    writableCreatePatterns: scope.writableCreatePatterns || [],
     writableConditional: scope.writableConditional || [],
     writableBroadFallback: scope.writableBroadFallback || [],
     forbidden: scope.forbidden || context.doNotTouch || [],
@@ -431,6 +435,12 @@ function repairFocusFromFind(findContext, userFocus) {
   if (isGenericAreaId(area)) goals.push(`replace generic area id with a focused id such as ${suggestedArea}`);
   if (warnings.includes('BROAD_WRITABLE_SCOPE')) goals.push('move broad writable scope to reviewed fallback');
   if (warnings.includes('MISSING_DIRECT_WRITABLE_SCOPE')) goals.push('add narrow writable_direct files');
+  if (warnings.includes('MISSING_DIRECT_NEW_FILE_SCOPE')) goals.push('add narrow writable_direct patterns or exact paths for the new peer files this intent must create');
+  if (warnings.includes('DIRECT_ONLY_REFERENCE_PEERS')) goals.push('move peer examples out of selected direct scope and add target create capability');
+  if (warnings.includes('BROAD_FALLBACK_ONLY')) goals.push('replace broad fallback-only coverage with narrow direct create capability');
+  if (warnings.includes('TARGET_ENTITY_MISMATCH')) goals.push('add direct scope for the requested target identity or mark old peers as references');
+  if (warnings.includes('MISSING_ARTIFACT_FAMILY_SCOPE')) goals.push('add writable_create_patterns for required artifact families');
+  if (warnings.includes('MISSING_REQUIRED_HOOK_SCOPE')) goals.push('add writable_existing hook files required by the artifact family');
   if (warnings.includes('MISSING_ENTRYPOINT')) goals.push('add durable entrypoints');
   if (warnings.includes('MISSING_VALIDATION')) goals.push('add validation profile references');
   if (warnings.includes('NO_CONFIDENT_AREA')) goals.push('create or refine a focused area');
@@ -464,6 +474,15 @@ function findContextPromptSection(findContext) {
     'Review-gated scope from find:',
     ...listLines(findContext.reviewGated, (notice) => `- ${notice.code}: ${notice.message}`),
     '',
+    ...(findContext.writePlan ? [
+      'Write plan from find:',
+      ...listLines(findContext.writePlan.hypotheses || [], (item) => `- ${item.action} ${item.artifactFamily}: ${item.operation}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''}`),
+      'Write plan blocking warnings:',
+      ...listLines(findContext.writePlan.blockingWarnings || [], (item) => `- ${item.code}: ${item.message}`),
+      'Reference files from write plan:',
+      ...listLines(findContext.writePlan.referenceFiles || [], (file) => `- ${file.path}: ${file.reason || ''}`),
+      '',
+    ] : []),
     'Candidate/area scores:',
     ...listLines(findContext.areaScores.length ? findContext.areaScores : findContext.candidateAreas, (area) => {
       const signals = area.signals && area.signals.length ? ` (${area.signals.slice(0, 3).join(', ')})` : '';
@@ -476,6 +495,15 @@ function findContextPromptSection(findContext) {
     'Current direct writable scope:',
     ...listLines(findContext.writableDirect, patternLine),
     '',
+    'Selected direct writable scope for this intent:',
+    ...listLines(findContext.selectedWritableScope, patternLine),
+    '',
+    'Current writable existing scope:',
+    ...listLines(findContext.writableExisting, patternLine),
+    '',
+    'Current writable create patterns:',
+    ...listLines(findContext.writableCreatePatterns, patternLine),
+    '',
     'Current conditional writable scope:',
     ...listLines(findContext.writableConditional, patternLine),
     '',
@@ -541,6 +569,9 @@ function buildMapPrompt(result) {
     '- Every `writable_conditional` and `writable_broad_fallback` item must set `requires_review: true`; never output `requires_review: false` for those tiers.',
     '- Keep broad patterns like `apps/*/src/**` only under `writable_broad_fallback`, never under `writable_direct`.',
     '- `writable_direct` should use exact existing files unless there is a very small, justified pattern.',
+    '- Prefer `writable_existing` for exact update targets and `writable_create_patterns` for new peer files when a repo has create/update distinctions.',
+    '- Put copy sources and peer examples under `readable_reference`, not under selected Direct Writable for new peer intents.',
+    '- Use `artifact_families` to declare required create artifacts and hook files for provider/adapter/endpoint families.',
     '- Entrypoint roles must use this fixed taxonomy only: ' + roleListText() + '.',
     '- Do not invent role names. If unsure, use `role: unknown` plus a TODO note.',
     '- Add `source` and `confidence` to entrypoints when possible. Use `source: agent_draft` for your own draft and `confidence: low|medium|high`.',
@@ -594,8 +625,27 @@ function buildMapPrompt(result) {
     '    scope:',
     '      readable:',
     '        - path/to/read/**',
+    '      readable_reference:',
+    '        peer_examples:',
+    '          - path: path/to/ExistingPeer.ts',
+    '            artifact: service_impl',
+    '            peer_identity: Existing',
     '      writable_direct:',
     '        - path/to/real/file.ts',
+    '      writable_existing:',
+    '        - path: path/to/Registry.ts',
+    '          artifact: registry_hook',
+    '          operations:',
+    '            - update_existing',
+    '          required_when:',
+    '            - add_provider_proxy',
+    '      writable_create_patterns:',
+    '        - pattern: path/to/*Provider.ts',
+    '          artifact: service_impl',
+    '          operations:',
+    '            - create_file',
+    '          intent_kinds:',
+    '            - add_provider_proxy',
     '      writable_conditional:',
     '        - pattern: path/to/shared/**',
     '          reason: only if shared model changes are required',
@@ -623,6 +673,19 @@ function buildMapPrompt(result) {
     '      default_level: low',
     '      tags:',
     '        - ui',
+    '    artifact_families:',
+    '      provider_proxy:',
+    '        trigger_terms:',
+    '          en:',
+    '            - provider',
+    '            - proxy',
+    '          zh:',
+    '            - 提供商',
+    '            - 代理',
+    '        create_requires:',
+    '          - service_impl',
+    '        hooks:',
+    '          - registry_hook',
     '```',
     '',
     'Validation profile schema example:',

package/src/lib/risk.js

@@ -54,6 +54,11 @@ function evaluateChangeRisk(change, map) {
   if (change.scope.status === 'violation') {
     blockingReasons.push(`scope violation: ${change.scope.violations.join(', ')}`);
   }
+  if (change.writePlanStatus && change.writePlanStatus.status === 'blocked') {
+    for (const reason of change.writePlanStatus.blockingReasons || []) {
+      blockingReasons.push(`write plan blocked: ${reason}`);
+    }
+  }
 
   const status = validationStatus(change);
   if (status === 'failed') blockingReasons.push('validation failed');

package/src/lib/scope.js

@@ -12,6 +12,12 @@ function patternFrom(value) {
   return normalizePath((value.pattern || value.path || '').trim());
 }
 
+function arrayFrom(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '')).filter(Boolean);
+  if (value == null || value === '') return [];
+  return [String(value)];
+}
+
 function normalizePattern(value, defaults = {}) {
   const pattern = patternFrom(value);
   if (!pattern) return null;
@@ -22,6 +28,13 @@ function normalizePattern(value, defaults = {}) {
       requiresReview: defaults.requiresReview === true,
       source: defaults.source || 'map',
       matchCount: defaults.matchCount == null ? null : defaults.matchCount,
+      artifact: defaults.artifact || null,
+      artifactFamily: defaults.artifactFamily || null,
+      operations: arrayFrom(defaults.operations),
+      targetIdentity: defaults.targetIdentity || null,
+      targetSlot: defaults.targetSlot || null,
+      intentKinds: arrayFrom(defaults.intentKinds),
+      requiredWhen: arrayFrom(defaults.requiredWhen),
     };
   }
   return {
@@ -30,6 +43,13 @@ function normalizePattern(value, defaults = {}) {
     requiresReview: value.requires_review === true || value.requiresReview === true || defaults.requiresReview === true,
     source: value.source || defaults.source || 'map',
     matchCount: value.matchCount == null ? (defaults.matchCount == null ? null : defaults.matchCount) : value.matchCount,
+    artifact: value.artifact || defaults.artifact || null,
+    artifactFamily: value.artifact_family || value.artifactFamily || defaults.artifactFamily || null,
+    operations: arrayFrom(value.operations || value.operation || defaults.operations),
+    targetIdentity: value.target_identity || value.targetIdentity || value.peer_identity || value.peerIdentity || defaults.targetIdentity || null,
+    targetSlot: value.target_slot || value.targetSlot || defaults.targetSlot || null,
+    intentKinds: arrayFrom(value.intent_kinds || value.intentKinds || defaults.intentKinds),
+    requiredWhen: arrayFrom(value.required_when || value.requiredWhen || defaults.requiredWhen),
   };
 }
 
@@ -93,29 +113,119 @@ function splitDirectAndBroad(root, values, defaults = {}) {
   return { direct, broad };
 }
 
+function splitItemsAndBroad(root, values, defaults = {}) {
+  const direct = [];
+  const broad = [];
+  for (const value of values || []) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const classification = isBroadPattern(root, pattern);
+    const item = normalizePattern(value, {
+      ...defaults,
+      matchCount: classification.matchCount,
+    });
+    if (!item) continue;
+    if (classification.broad) {
+      broad.push({
+        ...item,
+        reason: item.reason || classification.reason || 'broad writable scope',
+        requiresReview: true,
+      });
+    } else {
+      direct.push(item);
+    }
+  }
+  return { direct, broad };
+}
+
+function flattenReferenceValues(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'object' && (value.path || value.pattern)) return [value];
+  if (typeof value === 'object') {
+    return Object.values(value).flatMap((item) => flattenReferenceValues(item));
+  }
+  return [value];
+}
+
+function normalizeReference(value, defaults = {}) {
+  const pattern = patternFrom(value);
+  if (!pattern) return null;
+  if (typeof value === 'string') {
+    return {
+      path: pattern,
+      reason: defaults.reason || '',
+      role: defaults.role || 'reference',
+      artifact: defaults.artifact || null,
+      artifactFamily: defaults.artifactFamily || null,
+      peerIdentity: defaults.peerIdentity || null,
+      source: defaults.source || 'readable_reference',
+    };
+  }
+  return {
+    path: pattern,
+    reason: value.reason || defaults.reason || '',
+    role: value.role || defaults.role || 'reference',
+    artifact: value.artifact || defaults.artifact || null,
+    artifactFamily: value.artifact_family || value.artifactFamily || defaults.artifactFamily || null,
+    peerIdentity: value.peer_identity || value.peerIdentity || value.provider || defaults.peerIdentity || null,
+    source: value.source || defaults.source || 'readable_reference',
+  };
+}
+
+function normalizeReferenceList(value, defaults = {}) {
+  return flattenReferenceValues(value).map((item) => normalizeReference(item, defaults)).filter(Boolean);
+}
+
 function normalizeAreaScope(root, area = {}) {
   const configured = area.scope || {};
   const readable = (configured.readable || area.readable_scope || []).map(patternFrom).filter(Boolean);
+  const readableReference = normalizeReferenceList(configured.readable_reference || area.readable_reference || [], {
+    source: 'readable_reference',
+  });
   const forbidden = (configured.forbidden || area.do_not_touch || []).map(patternFrom).filter(Boolean);
 
   const directValues = configured.writable_direct || [];
+  const existingValues = configured.writable_existing || [];
+  const createValues = configured.writable_create_patterns || [];
   const conditionalValues = configured.writable_conditional || [];
   const broadValues = configured.writable_broad_fallback || [];
   const legacyWritable = !area.scope ? (area.writable_scope || []) : [];
 
-  const directSplit = splitDirectAndBroad(root, directValues, { source: 'writable_direct' });
+  const directSplit = splitItemsAndBroad(root, directValues, { source: 'writable_direct' });
+  const existingSplit = splitItemsAndBroad(root, existingValues, {
+    source: 'writable_existing',
+    operations: ['update_existing'],
+  });
+  const createSplit = splitItemsAndBroad(root, createValues, {
+    source: 'writable_create_patterns',
+    operations: ['create_file'],
+  });
   const legacySplit = splitDirectAndBroad(root, legacyWritable, {
     source: 'legacy_writable_scope',
     reason: 'legacy writable_scope is broad; move this to scope.writable_broad_fallback or add writable_direct',
   });
 
-  const writableDirect = [...directSplit.direct, ...legacySplit.direct];
+  const legacyDirectItems = legacySplit.direct.map((pattern) => normalizePattern(pattern, {
+    source: 'legacy_writable_scope',
+  })).filter(Boolean);
+  const writableDirectItems = [
+    ...directSplit.direct,
+    ...existingSplit.direct,
+    ...createSplit.direct,
+    ...legacyDirectItems,
+  ];
+  const writableDirect = writableDirectItems.map((item) => item.pattern);
+  const writableExisting = existingSplit.direct;
+  const writableCreatePatterns = createSplit.direct;
   const writableConditional = normalizePatternList(conditionalValues, {
     source: 'writable_conditional',
     requiresReview: true,
   });
   const writableBroadFallback = [
     ...directSplit.broad,
+    ...existingSplit.broad,
+    ...createSplit.broad,
     ...normalizePatternList(broadValues, {
       source: 'writable_broad_fallback',
       requiresReview: true,
@@ -139,7 +249,11 @@ function normalizeAreaScope(root, area = {}) {
 
   return {
     readable,
+    readableReference,
     writableDirect,
+    writableDirectItems,
+    writableExisting,
+    writableCreatePatterns,
     writableConditional,
     writableBroadFallback,
     forbidden,
@@ -164,5 +278,6 @@ module.exports = {
   itemPattern,
   normalizeAreaScope,
   normalizePatternList,
+  normalizeReferenceList,
   patternDisplay,
 };