docs(comments): strip internal task/milestone/bundle bookkeeping from code comments

Remove project bookkeeping citations from shipped code comments across the
solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/
issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels,
and C/D/K/S/T phase labels.

Comment text only — no code logic, string/log literals, or XML-doc structure
changed. Genuine descriptions are preserved (only the citation is stripped),
and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365,
UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker
TaskReferenceInComment / TrackingReferenceInComment checks plus targeted
grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
Joseph Doherty
2026-07-07 11:03:26 -04:00
parent 67005ca4c0
commit 9cff87fe85
435 changed files with 2338 additions and 2547 deletions
@@ -29,7 +29,7 @@ public class TemplateService
}
// ========================================================================
// WP-1: Template CRUD with Inheritance
// Template CRUD with Inheritance
// ========================================================================
/// <summary>
@@ -75,7 +75,7 @@ public class TemplateService
// collisions are enforced on every member-mutating call (AddAttribute,
// AddAlarm, AddScript, AddComposition) and on rename in UpdateTemplate.
// TemplateEngine-020: save the entity first so EF Core populates the
// Save the entity first so EF Core populates the
// auto-generated key, then write the audit row with the real
// template.Id, then save the audit row. The pre-fix order logged
// EntityId = "0" because the audit row was queued before
@@ -91,7 +91,7 @@ public class TemplateService
/// <summary>
/// Updates a template's name and (optionally) description. Optional fields use
/// leave-unchanged semantics so an omitted field is not silently wiped (followup #5):
/// leave-unchanged semantics so an omitted field is not silently wiped:
/// a <c>null</c> <paramref name="description"/> leaves the stored description as-is —
/// pass an empty string to explicitly clear it. Parent template is immutable after
/// creation; a <c>null</c> <paramref name="parentTemplateId"/> leaves it unchanged,
@@ -165,8 +165,8 @@ public class TemplateService
// Deletion-constraint logic (instances / child / derived / composing
// templates) lives in exactly one place — TemplateDeletionService — so a
// future rule change cannot drift between two implementations
// (TemplateEngine-014). TemplateService owns only the audit-logging side
// future rule change cannot drift between two implementations.
// TemplateService owns only the audit-logging side
// effect, which the deletion service is unaware of.
var deletionService = new Services.TemplateDeletionService(_repository);
var deleteResult = await deletionService.DeleteTemplateAsync(templateId, cancellationToken);
@@ -210,7 +210,7 @@ public class TemplateService
// folder cannot collide with itself).
if (template.FolderId != newFolderId)
{
// Sibling-name uniqueness at the destination (TemplateEngine-021),
// Sibling-name uniqueness at the destination,
// mirroring TemplateFolderService.MoveFolderAsync. A template move
// changes only FolderId, so there is no inheritance- or
// composition-graph cycle to detect (templates have no folder-
@@ -261,7 +261,7 @@ public class TemplateService
}
// ========================================================================
// WP-2: Attribute Definitions with Lock Flags
// Attribute Definitions with Lock Flags
// ========================================================================
/// <summary>
@@ -278,7 +278,7 @@ public class TemplateService
string user,
CancellationToken cancellationToken = default)
{
// Defense-in-depth (#92): hoist the (DataType, ElementDataType, Value)
// Defense-in-depth: hoist the (DataType, ElementDataType, Value)
// guard — previously only enforced on the CLI/API path in
// ManagementActor.ValidateAttributeTypes — into the service so the
// Central UI's direct TemplateService write path shares one server-side
@@ -306,14 +306,14 @@ public class TemplateService
if (collisions.Count > 0)
return Result<TemplateAttribute>.Failure(string.Join(" ", collisions));
// TemplateEngine-020: save-then-audit so the audit row carries the
// Save-then-audit so the audit row carries the
// real attribute Id rather than a literal "0".
await _repository.AddTemplateAttributeAsync(attribute, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "Create", "TemplateAttribute", attribute.Id.ToString(), attribute.Name, attribute, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the new member to derived descendants (#1/#2).
// Propagate the new member to derived descendants.
await ReconcileDescendantsAsync(templateId, user, cancellationToken);
return Result<TemplateAttribute>.Success(attribute);
@@ -337,7 +337,7 @@ public class TemplateService
if (existing == null)
return Result<TemplateAttribute>.Failure($"Attribute with ID {attributeId} not found.");
// Defense-in-depth (#92): hoist the (DataType, ElementDataType, Value)
// Defense-in-depth: hoist the (DataType, ElementDataType, Value)
// guard out of ManagementActor.ValidateAttributeTypes so the Central UI's
// direct TemplateService write path shares one server-side check. DataType
// and ElementDataType are fixed by the defining level (not copied from the
@@ -378,7 +378,7 @@ public class TemplateService
// LockedInDerived is a one-way ratchet on base templates: once a base
// marks an attribute LockedInDerived it cannot be cleared, otherwise
// derived overrides that were previously blocked would become
// retroactively legal (TemplateEngine-022). Only meaningful on base
// retroactively legal. Only meaningful on base
// templates — derived rows never carry an authoritative LockedInDerived.
if (template?.IsDerived != true)
{
@@ -410,7 +410,7 @@ public class TemplateService
await _auditService.LogAsync(user, "Update", "TemplateAttribute", attributeId.ToString(), existing.Name, existing, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the changed effective value to derived descendants (#1/#2).
// Propagate the changed effective value to derived descendants.
await ReconcileDescendantsAsync(existing.TemplateId, user, cancellationToken);
return Result<TemplateAttribute>.Success(existing);
@@ -448,7 +448,7 @@ public class TemplateService
await _auditService.LogAsync(user, "Delete", "TemplateAttribute", attributeId.ToString(), attribute.Name, null, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Remove the now-orphaned inherited placeholder from derived descendants (#1/#2).
// Remove the now-orphaned inherited placeholder from derived descendants.
await ReconcileDescendantsAsync(attribute.TemplateId, user, cancellationToken);
return Result<bool>.Success(true);
@@ -459,7 +459,7 @@ public class TemplateService
/// Returns a human-readable failure message (for <c>Result.Failure</c>), or
/// <c>null</c> when the triple is valid. Mirrors the CLI/API-path guard in
/// <c>ManagementActor.ValidateAttributeTypes</c> so both server write paths
/// share one server-side check (#92), reusing <see cref="AttributeValueCodec"/>
/// share one server-side check, reusing <see cref="AttributeValueCodec"/>
/// for the element-type and value-decode logic:
/// <list type="bullet">
/// <item>DataType must be a defined enum value.</item>
@@ -501,7 +501,7 @@ public class TemplateService
}
// ========================================================================
// WP-3: Alarm Definitions
// Alarm Definitions
// ========================================================================
/// <summary>
@@ -539,14 +539,14 @@ public class TemplateService
if (collisions.Count > 0)
return Result<TemplateAlarm>.Failure(string.Join(" ", collisions));
// TemplateEngine-020: save-then-audit so the audit row carries the
// Save-then-audit so the audit row carries the
// real alarm Id rather than a literal "0".
await _repository.AddTemplateAlarmAsync(alarm, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "Create", "TemplateAlarm", alarm.Id.ToString(), alarm.Name, alarm, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the new member to derived descendants (#1/#2).
// Propagate the new member to derived descendants.
await ReconcileDescendantsAsync(templateId, user, cancellationToken);
return Result<TemplateAlarm>.Success(alarm);
@@ -601,7 +601,7 @@ public class TemplateService
}
}
// One-way LockedInDerived ratchet on base templates (TemplateEngine-022).
// One-way LockedInDerived ratchet on base templates.
if (template?.IsDerived != true)
{
var lockedInDerivedError = LockEnforcer.ValidateLockedInDerivedChange(
@@ -631,7 +631,7 @@ public class TemplateService
await _auditService.LogAsync(user, "Update", "TemplateAlarm", alarmId.ToString(), existing.Name, existing, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the changed effective value to derived descendants (#1/#2).
// Propagate the changed effective value to derived descendants.
await ReconcileDescendantsAsync(existing.TemplateId, user, cancellationToken);
return Result<TemplateAlarm>.Success(existing);
@@ -668,14 +668,14 @@ public class TemplateService
await _auditService.LogAsync(user, "Delete", "TemplateAlarm", alarmId.ToString(), alarm.Name, null, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Remove the now-orphaned inherited placeholder from derived descendants (#1/#2).
// Remove the now-orphaned inherited placeholder from derived descendants.
await ReconcileDescendantsAsync(alarm.TemplateId, user, cancellationToken);
return Result<bool>.Success(true);
}
// ========================================================================
// WP-4: Script Definitions
// Script Definitions
// ========================================================================
/// <summary>
@@ -709,14 +709,14 @@ public class TemplateService
if (collisions.Count > 0)
return Result<TemplateScript>.Failure(string.Join(" ", collisions));
// TemplateEngine-020: save-then-audit so the audit row carries the
// Save-then-audit so the audit row carries the
// real script Id rather than a literal "0".
await _repository.AddTemplateScriptAsync(script, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
await _auditService.LogAsync(user, "Create", "TemplateScript", script.Id.ToString(), script.Name, script, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the new member to derived descendants (#1/#2).
// Propagate the new member to derived descendants.
await ReconcileDescendantsAsync(templateId, user, cancellationToken);
return Result<TemplateScript>.Success(script);
@@ -768,7 +768,7 @@ public class TemplateService
}
}
// One-way LockedInDerived ratchet on base templates (TemplateEngine-022).
// One-way LockedInDerived ratchet on base templates.
if (template?.IsDerived != true)
{
var lockedInDerivedError = LockEnforcer.ValidateLockedInDerivedChange(
@@ -787,7 +787,7 @@ public class TemplateService
existing.TriggerType = proposed.TriggerType;
existing.TriggerConfiguration = proposed.TriggerConfiguration;
existing.MinTimeBetweenRuns = proposed.MinTimeBetweenRuns;
// M2.5 (#9): per-script execution timeout is an overridable field.
// Per-script execution timeout is an overridable field.
existing.ExecutionTimeoutSeconds = proposed.ExecutionTimeoutSeconds;
existing.ParameterDefinitions = proposed.ParameterDefinitions;
existing.ReturnDefinition = proposed.ReturnDefinition;
@@ -802,7 +802,7 @@ public class TemplateService
await _auditService.LogAsync(user, "Update", "TemplateScript", scriptId.ToString(), existing.Name, existing, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Propagate the changed effective value to derived descendants (#1/#2).
// Propagate the changed effective value to derived descendants.
await ReconcileDescendantsAsync(existing.TemplateId, user, cancellationToken);
return Result<TemplateScript>.Success(existing);
@@ -839,14 +839,14 @@ public class TemplateService
await _auditService.LogAsync(user, "Delete", "TemplateScript", scriptId.ToString(), script.Name, null, cancellationToken);
await _repository.SaveChangesAsync(cancellationToken);
// Remove the now-orphaned inherited placeholder from derived descendants (#1/#2).
// Remove the now-orphaned inherited placeholder from derived descendants.
await ReconcileDescendantsAsync(script.TemplateId, user, cancellationToken);
return Result<bool>.Success(true);
}
// ========================================================================
// WP-6: Composition with Recursive Nesting
// Composition with Recursive Nesting
// ========================================================================
/// <summary>
@@ -911,7 +911,7 @@ public class TemplateService
// No global name pre-check: derived templates store their contained
// (slot) name, which need only be unique within the owner — and that is
// already enforced above and by the (TemplateId, InstanceName) index.
// TemplateEngine-020: CreateCascadedCompositionAsync already saves the
// CreateCascadedCompositionAsync already saves the
// composition row, so composition.Id is populated by the time control
// returns here — the audit row therefore carries the real Id instead
// of the pre-fix literal "0".
@@ -1035,8 +1035,8 @@ public class TemplateService
if (composition == null)
return Result<bool>.Failure($"Composition with ID {compositionId} not found.");
// Identify the slot-owned derived template (post Phase-3 migration this is the
// typical case; pre-migration the composition may still point at a base).
// Identify the slot-owned derived template (this is now the
// typical case; pre-migration data may still have the composition point at a base).
var composedTemplate = await _repository.GetTemplateByIdAsync(composition.ComposedTemplateId, cancellationToken);
await _repository.DeleteTemplateCompositionAsync(compositionId, cancellationToken);
@@ -1132,7 +1132,7 @@ public class TemplateService
// other member types (TemplateNativeAlarmSource), and the inheritance
// resolver + staleness summary count them — so materialize their inherited
// placeholders here too, or a freshly-composed derived template reports
// stale for every inherited native source (follow-up #1/#2).
// stale for every inherited native source.
foreach (var src in baseTemplate.NativeAlarmSources)
{
derived.NativeAlarmSources.Add(new TemplateNativeAlarmSource(src.Name)
@@ -1151,15 +1151,15 @@ public class TemplateService
}
// ========================================================================
// Inherited-member propagation & resync (follow-up #1/#2)
// Inherited-member propagation & resync
// ========================================================================
//
// A derived template stores IsInherited placeholder rows mirroring the
// members it inherits. BuildDerivedTemplate materializes them at compose time,
// but a member ADDED / UPDATED / REMOVED on a base AFTER the derivation
// existed never reached the children — so derived row-sets drifted incomplete
// (the editor's editable tabs missed inherited members; #1) and stored rows
// diverged from the resolved set (#2). Two mechanisms keep them in sync:
// (the editor's editable tabs missed inherited members) and stored rows
// diverged from the resolved set. Two mechanisms keep them in sync:
// • ReconcileDescendantsAsync — called automatically after every base member
// mutation, propagates the change to the whole derived subtree.
// • ResyncInheritedMembersAsync — an explicit operator action (CLI + UI)
@@ -1573,7 +1573,7 @@ public class TemplateService
}
// ========================================================================
// WP-7: Path-Qualified Canonical Naming (via TemplateResolver)
// Path-Qualified Canonical Naming (via TemplateResolver)
// ========================================================================
/// <summary>
@@ -1591,12 +1591,12 @@ public class TemplateService
}
// ========================================================================
// WP-8/9/10/11: Override validation (integrated into Update* methods above)
// Override validation (integrated into Update* methods above)
// ========================================================================
/// <summary>
/// Validates whether overriding a member by canonical name is allowed.
/// Used for composition overrides (WP-11) and inheritance overrides (WP-10).
/// Used for composition overrides and inheritance overrides.
/// </summary>
/// <param name="templateId">ID of the template.</param>
/// <param name="canonicalName">Canonical name of the member to validate.</param>
@@ -1625,7 +1625,7 @@ public class TemplateService
}
// ========================================================================
// WP-12: Naming Collision Detection
// Naming Collision Detection
// ========================================================================
/// <summary>
@@ -1647,7 +1647,7 @@ public class TemplateService
}
// ========================================================================
// WP-13: Graph Acyclicity
// Graph Acyclicity
// ========================================================================
/// <summary>