hive-lite 0.1.8 → 0.2.0

package/src/lib/context.js

@@ -54,7 +54,7 @@ function isCreateCapablePattern(pattern) {
   return !looksLikeFilePattern(pattern);
 }
 
-const IDENTITY_ALIASES = {
+const DEFAULT_IDENTITY_ALIASES = {
   openai: ['openai', 'chatgpt', 'gpt'],
   google: ['google', 'gemini'],
   qwen: ['qwen', 'tongyi'],
@@ -64,37 +64,101 @@ const IDENTITY_ALIASES = {
   azure: ['azure'],
 };
 
-function canonicalIdentity(value) {
+function identityAliasList(config) {
+  if (Array.isArray(config)) return arrayFrom(config);
+  if (config && typeof config === 'object') {
+    return [
+      ...arrayFrom(config.aliases || config.alias),
+      ...arrayFrom(config.tokens),
+    ];
+  }
+  return arrayFrom(config);
+}
+
+function identityDisplayName(identity, area) {
+  const raw = area && (area.identity_aliases || area.identityAliases) ? area.identity_aliases || area.identityAliases : null;
+  if (raw) {
+    const entries = Array.isArray(raw)
+      ? raw.map((item) => [item && (item.id || item.name || item.canonical), item])
+      : Object.entries(raw);
+    for (const [id, config] of entries) {
+      const candidate = (config && typeof config === 'object' ? config.canonical || config.id || config.name : null) || id;
+      if (normalize(candidate) === normalize(identity)) return String(candidate);
+    }
+  }
+  return normalize(identity).split(/[^a-z0-9]+/).filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('') || String(identity || '');
+}
+
+function aliasRegistryForArea(area) {
+  const registry = Object.fromEntries(Object.entries(DEFAULT_IDENTITY_ALIASES)
+    .map(([canonical, aliases]) => [canonical, unique([canonical, ...aliases.map(normalize)])]));
+  const raw = area && (area.identity_aliases || area.identityAliases) ? area.identity_aliases || area.identityAliases : null;
+  if (!raw) return registry;
+
+  const entries = Array.isArray(raw)
+    ? raw.map((item) => [item && (item.id || item.name || item.canonical), item])
+    : Object.entries(raw);
+  for (const [id, config] of entries) {
+    if (!config) continue;
+    const canonical = normalize(
+      (typeof config === 'object' ? config.canonical || config.id || config.name : null)
+      || id
+    );
+    if (!canonical) continue;
+    const aliases = identityAliasList(config);
+    registry[canonical] = unique([
+      ...(registry[canonical] || []),
+      canonical,
+      normalize(id),
+      ...aliases.map(normalize),
+    ].filter(Boolean));
+  }
+  return registry;
+}
+
+function isKnownIdentity(value, aliases = DEFAULT_IDENTITY_ALIASES) {
+  return Object.prototype.hasOwnProperty.call(aliases, value);
+}
+
+function canonicalIdentity(value, aliases = DEFAULT_IDENTITY_ALIASES) {
   const text = normalize(value);
   if (!text) return null;
-  for (const [canonical, aliases] of Object.entries(IDENTITY_ALIASES)) {
-    if (aliases.includes(text)) return canonical;
+  for (const [canonical, values] of Object.entries(aliases)) {
+    if (canonical === text || values.includes(text)) return canonical;
   }
   return text;
 }
 
-function targetIdentityForIntent(intent) {
+function targetIdentityForIntent(intent, aliases) {
   const tokens = tokenize(intent);
   for (const token of tokens) {
-    const identity = canonicalIdentity(token);
-    if (identity && Object.prototype.hasOwnProperty.call(IDENTITY_ALIASES, identity)) return identity;
+    const identity = canonicalIdentity(token, aliases);
+    if (identity && isKnownIdentity(identity, aliases)) return identity;
   }
   return null;
 }
 
-function peerIdentityFromPath(pattern) {
+function targetIdentitiesForIntent(intent, aliases) {
+  return unique(tokenize(intent)
+    .map((token) => canonicalIdentity(token, aliases))
+    .filter((identity) => identity && isKnownIdentity(identity, aliases)));
+}
+
+function peerIdentityFromPath(pattern, aliases) {
   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;
+    const identity = canonicalIdentity(token, aliases);
+    if (identity && isKnownIdentity(identity, aliases)) return identity;
   }
   return null;
 }
 
-function identityMatches(left, right) {
+function identityMatches(left, right, aliases) {
   if (!left || !right) return false;
-  return canonicalIdentity(left) === canonicalIdentity(right);
+  return canonicalIdentity(left, aliases) === canonicalIdentity(right, aliases);
 }
 
 function intentTargetsAllPeers(intent) {
@@ -141,6 +205,50 @@ function configuredArtifactFamilies(area) {
   }));
 }
 
+function configuredPeerFileTemplates(area) {
+  const raw = area && (area.peer_file_templates || area.peerFileTemplates) ? area.peer_file_templates || area.peerFileTemplates : null;
+  if (!raw) return [];
+  const groups = Array.isArray(raw)
+    ? raw.map((item) => [item && (item.id || item.name || item.artifact_family || item.artifactFamily), item])
+    : Object.entries(raw);
+  const templates = [];
+  for (const [id, value] of groups) {
+    if (!value) continue;
+    const group = typeof value === 'object' && !Array.isArray(value) ? value : {};
+    const artifacts = group.artifacts || group.files || group.templates || (typeof value === 'object' && !Array.isArray(value) ? value : {});
+    for (const [artifactId, artifactValue] of Object.entries(artifacts || {})) {
+      const template = typeof artifactValue === 'string'
+        ? artifactValue
+        : artifactValue && (artifactValue.path || artifactValue.template || artifactValue.pattern);
+      if (!template) continue;
+      templates.push({
+        id: id || group.id || group.name || '',
+        artifact: typeof artifactValue === 'object' && artifactValue.artifact ? artifactValue.artifact : artifactId,
+        artifactFamily: group.artifact_family || group.artifactFamily || id || '',
+        targetSlot: group.target_slot || group.targetSlot || null,
+        template: String(template),
+        intentKinds: arrayFrom(group.intent_kinds || group.intentKinds),
+        reason: (typeof artifactValue === 'object' && artifactValue.reason) || group.reason || '',
+      });
+    }
+  }
+  return templates;
+}
+
+function peerTemplateFamilyMatches(template, hypothesis) {
+  const templateFamily = normalize(template.artifactFamily).replace(/-/g, '_');
+  const artifactFamily = normalize(hypothesis.artifactFamily).replace(/-/g, '_');
+  if (!templateFamily || !artifactFamily || artifactFamily === 'unknown') return true;
+  return templateFamily === artifactFamily || templateFamily.endsWith(artifactFamily);
+}
+
+function peerTemplateApplies(template, hypothesis) {
+  if (template.intentKinds.length > 0 && !template.intentKinds.includes(hypothesis.intentKind)) return false;
+  if (!peerTemplateFamilyMatches(template, hypothesis)) return false;
+  if (hypothesis.createRequires.length > 0 && !hypothesis.createRequires.includes(template.artifact)) return false;
+  return true;
+}
+
 function configuredArtifactFamilyForIntent(area, intent) {
   const text = normalize(intent);
   for (const family of configuredArtifactFamilies(area)) {
@@ -189,10 +297,15 @@ function classifyArtifactFamily(intent, area) {
 }
 
 function classifyIntentWrite(intent, area) {
+  const identityAliases = aliasRegistryForArea(area);
   const text = normalize(intent);
-  const createTerm = [
-    /\b(add|create|new|introduce|support|implement)\b/,
-    /新增|新建|创建|添加|接入|支持/,
+  const strongCreateTerm = [
+    /\b(create|new|introduce|implement)\b/,
+    /新增|新建|创建|接入/,
+  ].some((pattern) => pattern.test(text));
+  const createTerm = strongCreateTerm || [
+    /\b(add|support)\b/,
+    /添加|支持/,
   ].some((pattern) => pattern.test(text));
   const deleteTerm = [
     /\b(delete|remove)\b/,
@@ -205,7 +318,8 @@ function classifyIntentWrite(intent, area) {
   const targetAll = intentTargetsAllPeers(intent);
   const artifactFamily = classifyArtifactFamily(intent, area);
   const familyConfig = configuredArtifactFamilies(area).find((item) => item.id === artifactFamily) || null;
-  const targetIdentity = targetIdentityForIntent(intent);
+  const targetIdentity = targetIdentityForIntent(intent, identityAliases);
+  const targetIdentities = targetIdentitiesForIntent(intent, identityAliases);
   let action = 'modify';
   if (deleteTerm) action = 'delete';
   else if (renameTerm) action = 'rename';
@@ -214,6 +328,7 @@ function classifyIntentWrite(intent, area) {
     action,
     artifactFamily,
     targetIdentity,
+    targetIdentities,
     operation: action === 'create' && artifactFamily === 'provider_proxy' ? 'create_file' : 'modify_existing_file',
     required: true,
     targetAll,
@@ -221,10 +336,11 @@ function classifyIntentWrite(intent, area) {
     createRequires: familyConfig ? familyConfig.createRequires : [],
     hooks: familyConfig ? familyConfig.hooks : [],
     confidence: artifactFamily === 'unknown' ? 'low' : 'medium',
+    strongCreateIntent: strongCreateTerm,
   };
 }
 
-function directCapabilities(scope) {
+function directCapabilities(scope, identityAliases) {
   const explicitItems = [
     ...(scope.writableDirectItems || []),
   ];
@@ -248,12 +364,14 @@ function directCapabilities(scope) {
       breadth: createCapable ? 'narrow_pattern' : 'exact',
       reviewGated: false,
       source: item.source || 'writable_direct',
+      operationSpecified: configuredOperations.length > 0,
       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),
+      peerIdentity: canonicalIdentity(item.targetIdentity || item.target_identity || item.peerIdentity || item.peer_identity, identityAliases)
+        || peerIdentityFromPath(pattern, identityAliases),
     };
   }).filter(Boolean);
 }
@@ -288,32 +406,155 @@ function capabilityMatchesIntent(capability, hypothesis) {
   return capability.intentKinds.includes(hypothesis.intentKind);
 }
 
+function expandPeerTemplate(template, hypothesis, area) {
+  if (!hypothesis.targetIdentity) return template;
+  const label = identityDisplayName(hypothesis.targetIdentity, area);
+  const lower = normalize(hypothesis.targetIdentity);
+  return template
+    .replace(/\{Provider\}|\{Identity\}|\{Target\}/g, label)
+    .replace(/\{provider\}|\{identity\}|\{target\}/g, lower)
+    .replace(/\{PROVIDER\}|\{IDENTITY\}|\{TARGET\}/g, lower.toUpperCase());
+}
+
+function peerFileCandidatesFor(area, hypothesis) {
+  return configuredPeerFileTemplates(area)
+    .filter((item) => peerTemplateApplies(item, hypothesis))
+    .map((item) => ({
+      artifact: item.artifact,
+      artifactFamily: item.artifactFamily,
+      targetSlot: item.targetSlot,
+      targetIdentity: hypothesis.targetIdentity || null,
+      template: item.template,
+      candidatePath: expandPeerTemplate(item.template, hypothesis, area),
+      writable: false,
+      reason: item.reason || 'peer_file_templates are read-only hints; use writable_create_patterns to grant create permission',
+    }));
+}
+
+function selectedCapabilitiesFor(capabilities, selected) {
+  const selectedSet = new Set(selected);
+  return capabilities.filter((item) => selectedSet.has(item.scope));
+}
+
+function directReferenceConflicts(references, capabilities) {
+  const conflicts = [];
+  for (const reference of references) {
+    const referencePath = reference.path || reference.pattern;
+    if (!referencePath) continue;
+    const capability = capabilities.find((item) => (
+      item.source !== 'writable_create_patterns'
+      && item.operations.includes('update_existing')
+      && matchesPattern(referencePath, item.scope)
+    ));
+    if (capability) {
+      conflicts.push({
+        path: referencePath,
+        directScope: capability.scope,
+      });
+    }
+  }
+  return conflicts;
+}
+
+function unspecifiedOperationScopes(capabilities, hypothesis) {
+  return capabilities
+    .filter((item) => (
+      item.source === 'writable_direct'
+      && item.operationSpecified === false
+      && (hypothesis.operation === 'create_file' || item.operations.includes('create_file'))
+    ))
+    .map((item) => item.scope);
+}
+
+function certificateOperation(capability, hypothesis) {
+  if (hypothesis.operation === 'create_file' && capability.operations.includes('create_file')) return 'create_file';
+  if (capability.operations.includes('update_existing')) return 'update_existing';
+  return capability.operations[0] || hypothesis.operation || 'update_existing';
+}
+
+function certificateMapEntry(area, capability) {
+  const areaId = area && area.id ? area.id : 'unknown_area';
+  const source = capability.source || 'writable_direct';
+  const label = capability.artifact || capability.artifactFamily || null;
+  return label ? `${areaId}.scope.${source}.${label}` : `${areaId}.scope.${source}`;
+}
+
+function buildCapabilityCertificate(area, capability, hypothesis) {
+  const operation = certificateOperation(capability, hypothesis);
+  return {
+    path: capability.scope,
+    scope: capability.scope,
+    operation,
+    artifact: capability.artifact || null,
+    artifactFamily: capability.artifactFamily || hypothesis.artifactFamily || null,
+    targetIdentity: capability.peerIdentity || hypothesis.targetIdentity || null,
+    status: 'certified',
+    certifiedBy: {
+      mapEntry: certificateMapEntry(area, capability),
+      source: capability.source || 'writable_direct',
+      pattern: capability.scope,
+      intentKind: hypothesis.intentKind,
+    },
+  };
+}
+
+function certificatesForSelected(area, capabilities, selected, hypothesis) {
+  return selectedCapabilitiesFor(capabilities, selected).map((capability) => (
+    buildCapabilityCertificate(area, capability, hypothesis)
+  ));
+}
+
+/*
+ * Write permission is certified here, not by relevance alone:
+ * relevant files, entrypoints, peer examples, and broad fallback scopes may help
+ * an agent understand the repo, but they do not become Direct Writable unless
+ * they cover the inferred required write operation narrowly for this intent.
+ */
 function buildWritePlan(scope, intent, area) {
+  const identityAliases = aliasRegistryForArea(area);
   const hypothesis = classifyIntentWrite(intent, area);
-  const capabilities = directCapabilities(scope);
+  const capabilities = directCapabilities(scope, identityAliases);
   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),
+      peerIdentity: canonicalIdentity(item.peerIdentity, identityAliases) || peerIdentityFromPath(item.path, identityAliases),
     },
     item.reason || 'readable reference from Project Map'
   ));
+  const peerFileCandidates = peerFileCandidatesFor(area, hypothesis);
   let selected = capabilities.map((item) => item.scope);
 
+  if (hypothesis.targetIdentities && hypothesis.targetIdentities.length > 1 && !hypothesis.targetAll) {
+    warnings.push(warning(
+      'AMBIGUOUS_TARGET_IDENTITY',
+      `Intent mentions multiple target identities (${hypothesis.targetIdentities.join(', ')}); Direct Writable must be selected for one unambiguous target.`,
+      { targetIdentities: hypothesis.targetIdentities }
+    ));
+  }
+  if (hypothesis.confidence === 'low' && hypothesis.action !== 'modify' && (hypothesis.strongCreateIntent || hypothesis.action !== 'create')) {
+    warnings.push(warning(
+      'LOW_CONFIDENCE_INTENT_WRITE_PLAN',
+      'Intent appears to require writes, but Hive Lite could not infer a known artifact family for the required write plan.',
+      { action: hypothesis.action, artifactFamily: hypothesis.artifactFamily }
+    ));
+  }
+
   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')
+      item.source === 'writable_existing'
+      && !item.operations.includes('create_file')
+      && (!item.peerIdentity || identityMatches(item.peerIdentity, hypothesis.targetIdentity, identityAliases))
     ));
     const referencePeers = capabilities.filter((item) => (
       item.peerIdentity
       && hypothesis.targetIdentity
-      && !identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+      && !identityMatches(item.peerIdentity, hypothesis.targetIdentity, identityAliases)
     ));
     const selectedCreateCapabilities = hypothesis.createRequires.length
       ? createCapabilities.filter((item) => hypothesis.createRequires.some((artifact) => artifactMatches(item, artifact)))
@@ -374,13 +615,13 @@ function buildWritePlan(scope, intent, area) {
     && !hypothesis.targetAll
   ) {
     const targetMatches = capabilities.filter((item) => (
-      item.peerIdentity && identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+      item.peerIdentity && identityMatches(item.peerIdentity, hypothesis.targetIdentity, identityAliases)
     ));
     const genericCapabilities = capabilities.filter((item) => (
       !item.peerIdentity && !item.operations.includes('create_file')
     ));
     const referencePeers = capabilities.filter((item) => (
-      item.peerIdentity && !identityMatches(item.peerIdentity, hypothesis.targetIdentity)
+      item.peerIdentity && !identityMatches(item.peerIdentity, hypothesis.targetIdentity, identityAliases)
     ));
     selected = unique([...targetMatches, ...genericCapabilities].map((item) => item.scope));
     for (const capability of referencePeers) {
@@ -398,11 +639,31 @@ function buildWritePlan(scope, intent, area) {
   }
 
   selected = unique(selected);
+  const selectedCapabilities = selectedCapabilitiesFor(capabilities, selected);
+  const selectedWritableCertificates = certificatesForSelected(area, capabilities, selected, hypothesis);
+  const referenceConflicts = directReferenceConflicts(references, selectedCapabilities);
+  if (referenceConflicts.length > 0) {
+    warnings.push(warning(
+      'REFERENCE_DIRECT_ROLE_CONFLICT',
+      'One or more reference files also match selected Direct Writable update scope; keep peer examples reference-only or move new-file permission to writable_create_patterns.',
+      { blocking: false, conflicts: referenceConflicts }
+    ));
+  }
+  const unspecifiedScopes = unspecifiedOperationScopes(selectedCapabilities, hypothesis);
+  if (unspecifiedScopes.length > 0) {
+    warnings.push(warning(
+      'DIRECT_SCOPE_OPERATION_UNSPECIFIED',
+      'Selected Direct Writable scope relies on inferred operations; declare operations under writable_existing or writable_create_patterns for safer write certification.',
+      { blocking: false, scopes: unspecifiedScopes }
+    ));
+  }
   return {
     hypotheses: [hypothesis],
     capabilities,
     selectedWritableDirect: selected,
+    selectedWritableCertificates,
     referenceFiles: references,
+    peerFileCandidates,
     blockingWarnings: warnings.filter((item) => item.blocking !== false),
     warnings,
   };
@@ -677,9 +938,10 @@ function competingHighScoringAreas(scored) {
   ));
 }
 
-function decompositionSignals({ map, area, confidence, intent, relevant, scope, scored, validationPlan, constrainedAreaId }) {
+function decompositionSignals({ map, area, confidence, intent, relevant, scope, selectedWritableDirect, scored, validationPlan, constrainedAreaId }) {
   if (!area) return [];
   const signals = [];
+  const writableDirectForIntent = selectedWritableDirect || scope.writableDirect || [];
   const highAreas = highScoringAreas(scored)
     .filter((item) => !constrainedAreaId || item.area.id === constrainedAreaId);
   const competingAreas = competingHighScoringAreas(scored)
@@ -711,16 +973,16 @@ function decompositionSignals({ map, area, confidence, intent, relevant, scope,
     }));
   }
 
-  if (scope.writableDirect.length > DECOMPOSITION_LIMITS.writableFilesBlocking) {
+  if (writableDirectForIntent.length > DECOMPOSITION_LIMITS.writableFilesBlocking) {
     signals.push(signal('TOO_MANY_WRITABLE_FILES', 'Direct writable files exceed the safe change boundary.', {
-      count: scope.writableDirect.length,
+      count: writableDirectForIntent.length,
       threshold: DECOMPOSITION_LIMITS.writableFilesBlocking,
     }));
-  } else if (scope.writableDirect.length > DECOMPOSITION_LIMITS.writableFilesWarning) {
+  } else if (writableDirectForIntent.length > DECOMPOSITION_LIMITS.writableFilesWarning) {
     signals.push(signal('TOO_MANY_WRITABLE_FILES', 'Direct writable files are high for one Change Record.', {
       severity: 'warning',
       blocking: false,
-      count: scope.writableDirect.length,
+      count: writableDirectForIntent.length,
       threshold: DECOMPOSITION_LIMITS.writableFilesWarning,
     }));
   }
@@ -777,8 +1039,8 @@ function candidatePhaseSeeds(scored, intent) {
       phaseHint: area.name || area.id,
       findIntent: `${intent} [focus: ${area.id}]`,
       roles,
-      evidenceClasses: evidenceClassesForRoles(roles),
-      validationProfiles: ((area.validation || {}).profiles || []).filter(Boolean),
+      evidenceClasses: unique(evidenceClassesForRoles(roles)),
+      validationProfiles: unique(((area.validation || {}).profiles || []).filter(Boolean)),
       risk: riskLevelFor(area),
       reason: item.signals.slice(0, 4).join(', '),
     };
@@ -823,14 +1085,14 @@ function buildSplitMarkdown(note) {
       '',
       `Area: ${phase.primaryAreaId}`,
       '',
-      'Run with this Hive Lite CLI invocation:',
+      'Copy one command block below to run this phase. Do not append the notes after it.',
       '',
       '```bash',
       findCommandForPhase(currentArgv, note, phase),
       '```',
       '',
       ...(!sameArgv(currentArgv, packageAliasArgv) ? [
-        'If the package alias is installed:',
+        'Or, if the package alias is installed:',
         '',
         '```bash',
         findCommandForPhase(packageAliasArgv, note, phase),
@@ -892,10 +1154,10 @@ function createSplitNote(root, packet, phaseSeeds, decomposition, options = {})
       title: phase.phaseHint,
       findIntent: phase.findIntent,
       primaryAreaId: phase.areaId,
-      expectedEvidence: [
+      expectedEvidence: unique([
         ...(phase.validationProfiles || []).map((profile) => `validation:${profile}`),
         ...(phase.evidenceClasses || []).map((item) => `evidence:${item}`),
-      ],
+      ]),
       nonGoals: phaseSeeds
         .filter((other) => other.areaId !== phase.areaId)
         .map((other) => `Do not change ${other.areaId} in this phase.`),
@@ -1110,6 +1372,8 @@ function hasBlockingMapGapWarning(warnings = []) {
     'TARGET_ENTITY_MISMATCH',
     'MISSING_ARTIFACT_FAMILY_SCOPE',
     'MISSING_REQUIRED_HOOK_SCOPE',
+    'AMBIGUOUS_TARGET_IDENTITY',
+    'LOW_CONFIDENCE_INTENT_WRITE_PLAN',
   ].includes(warning.code));
 }
 
@@ -1238,11 +1502,21 @@ function buildContextMarkdown(packet) {
         : ['- Coverage: direct writable scope covers the inferred write operation.']),
       '',
     ] : []),
+    ...(packet.writePlan && packet.writePlan.selectedWritableCertificates && packet.writePlan.selectedWritableCertificates.length ? [
+      '## Certified Direct Writable',
+      ...packet.writePlan.selectedWritableCertificates.map((item) => `- ${item.path}: ${item.operation}${item.artifact ? ` ${item.artifact}` : ''}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''} (certified by ${item.certifiedBy && item.certifiedBy.mapEntry ? item.certifiedBy.mapEntry : 'unknown map entry'})`),
+      '',
+    ] : []),
     ...(packet.writePlan && packet.writePlan.referenceFiles.length ? [
       '## Reference Files',
       ...packet.writePlan.referenceFiles.map((file) => `- ${file.path}: ${file.reason}`),
       '',
     ] : []),
+    ...(packet.writePlan && packet.writePlan.peerFileCandidates && packet.writePlan.peerFileCandidates.length ? [
+      '## Peer File Template Candidates',
+      ...packet.writePlan.peerFileCandidates.map((file) => `- ${file.artifact}: ${file.candidatePath || file.template} (read-only hint; not Direct Writable)`),
+      '',
+    ] : []),
     '## Relevant Files',
     ...packet.relevantFiles.map((file) => `- ${file.path} (${file.role || file.source}): ${file.reason}`),
     '',
@@ -1334,7 +1608,9 @@ function createContextPacket(root, intent, options = {}) {
     hypotheses: [],
     capabilities: [],
     selectedWritableDirect: [],
+    selectedWritableCertificates: [],
     referenceFiles: [],
+    peerFileCandidates: [],
     blockingWarnings: [],
     warnings: [],
   };
@@ -1403,6 +1679,7 @@ function createContextPacket(root, intent, options = {}) {
     intent,
     relevant,
     scope,
+    selectedWritableDirect: writePlan.selectedWritableDirect,
     scored,
     validationPlan,
     constrainedAreaId,

package/src/lib/git.js

@@ -123,6 +123,7 @@ module.exports = {
   repoRoot,
   requireGitRepo,
   runGit,
+  runGitRaw,
   statusLines,
   tryGit,
 };