Skip to content

Documentation Inconsistencies

This document tracks inconsistencies and misalignments between the AI Factory documentation and the company documentation. It serves as a reference for identifying areas that need alignment, content gaps, and solution misalignments.

Note

This document is maintained as a living reference. Items are removed as inconsistencies are resolved.

Recent Resolutions

Vision and Strategy Alignment (Completed): - Strategic Goals document enhanced with Core Concepts, Strategic Themes, Time Horizons, and Business Strategy alignment - Vision Overview document enhanced with Factory's role in ConnectSoft ecosystem and Strategic Moat sections - Why AI Software Factory document aligned with company documentation version - Terminology consistency verified (Core Platform, SaaS Cycles, 4 Pillars) - All timelines verified to start from January 1, 2026 - Technology stack references updated (.NET 10+, Microsoft.Extensions.AI, Agent Framework)

2026-10 reassessment: drift found during the plane restructure

Recorded 2026-10-09 by the independent review that followed the 2026-10-08 handoff (handoffs/2026-10-09-independent-review/). The site is being restructured from twelve platforms to planes; items below are Factory-side facts verified against the repositories at Factory docs HEAD d8d43f40. Each row is closed when the referenced page is revised.

Finding Where Governing decision Action and status
Site structure: platforms/overview.md defines a five-plane model (Experience, Control, Work, Delivery & Runtime, Cross-cutting) that is superseded by the nine-plane structure chosen on 2026-10-08. platforms/overview.md, all platforms/* Decision D2/D8 (decision log in the review folder) Rewritten as the plane map in WP-2; platform folders migrated under planes and solution packs in WP-4…WP-8; the plane map now lives at ai-software-factory/plane-map.md; platforms/ holds only redirects. Done 2026-10-09
Target described as current: the page says "This page describes the current implementation architecture" in an admonition titled "Final-state architecture", then describes "a fully autonomous, AI-driven platform". No control plane, registry, durable run, approval or Studio exists in code. platform-architecture/overall-architecture.md L14–L19 Status convention (Target / Current / Decision / Evidence / Historical) Relabelled historical, admonition corrected in WP-2; listed under Architecture & Decisions → Historical. Done 2026-10-09
Home page promises "complete, production-ready SaaS systems" produced by "autonomous AI agents"; presentation HTML (csf-hero, card grids). index.md L14–L54 D1 product framing; documentation standard (Markdown, no decorative HTML) Rewritten in WP-2 (Markdown only, D1 framing). Done 2026-10-09
Eleven ADRs all carry the placeholder date 2026-01-01; ADR-0003 (MassTransit on Azure Service Bus) and ADR-0005 (Qdrant primary) conflict with the user's direction and with the code (the agent host wires only the in-memory vector store). architecture/adr/0001…0011 D9 Review notes added; Proposed ADR-0012…0015 written in WP-2; ADR-0004 verified and retained. Done 2026-10-09 (amendments stay Proposed until the owner accepts them)
Roadmap pages dated 2025-12-17 carry 2026 milestones that have passed without evidence and 2027–2029 targets ("> 95 % autonomous", "market dominance"). roadmap/*.md, mvp/*.md D5 Archived with historical banner and search: exclude; replaced by architecture/capability-dependencies.md. Done 2026-10-09
.NET 9 text defect: "compatible with .NET 10, .NET 9, and .NET 10" while the .NET 8/9 cleanup is marked resolved below. templates-docs/libraries-list.md:15; also platform-architecture/blueprints/backend-library-blueprint.md:855 ADR-0001 Wording fixed in both pages (libraries multi-target .NET 8/9/10; hosts .NET 10). Done 2026-10-09
Stale checkout path C:\Git\ConnectSoft\SAAS\; the five SaaS template repositories are directly under C:\Git\ConnectSoft. agents/detailed-agent-specifications/microservice-generator-agent.md:553, platform-architecture/template-catalog.md:306, templates-docs/microservice-template/legacy-deep-dive.md:29 — Path replaced in WP-1; generator-agent page annotated "Provisional — commitment deferred (Q-22)" in WP-8. Done 2026-10-09
Eleven cross-repository relative links (../../../ConnectSoft.Documentation/Docs/starters/...) resolve on disk but not in the built site. same three pages (2 + 5 + 4 links) Canonical pages are linked by URL, never copied Replaced by absolute canonical-site URLs or plain references in WP-1. Done 2026-10-09
Two glossaries with overlapping terms. glossary.md, ai-software-factory/glossary.md Documentation standard Merged into glossary.md (structural terms, status labels, corrected stack table); old path redirects. Done 2026-10-09
22 pages have no body (5 platform-foundations, 9 Studio, 3 template groups, 4 agent specs, references.md). The nine Studio pages are byte-identical to copies in ConnectSoft.DesignPrototypes/uploads/ai-software-factory-studio/. listed in handoffs/2026-10-08-ai-factory/analysis/documentation-completion-handoff.md D6 All 22 filled with status-labelled content in WP-2…WP-8. Done 2026-10-09
Service catalog lists 162 rows with six names appearing under two platforms (AgentRegistryService, SkillRegistryService, AgentPoolManager; PolicyEngineService, ApprovalService, AuditService). catalogs/microservice-catalog.md D2a Replaced by architecture/ownership-map.md with one authoritative owner per capability; catalogs/microservice-catalog.md redirects to it. Done 2026-10-09
requirements-docs.txt lists only mkdocs-material and pymdown-extensions although mkdocs.yml uses the panzoom and exclude plugins; not_in_nav has two malformed - entries. repo root, mkdocs.yml D14 Fixed in WP-1 (mkdocs-redirects, mkdocs-panzoom-plugin, mkdocs-exclude listed; not_in_nav corrected). Done 2026-10-09
Repository contains config-platform/ (22 tracked files, a "Config Platform product repository" demonstration) and _product-repository-template/, _artifact-repository-template/, all outside nav. Config Platform documentation moved to the canonical repository on 2026-09-29. repo root D13 Inventory only; no change in this task. Recorded

Final-State Architecture Alignment (twelve-platform model)

The final-state architecture documentation set (ai-software-factory/, platforms/, architecture/, catalogs/, reference/) is now the primary, authoritative description of the target system. Existing implementation docs have been re-homed under the Implementation nav tab and linked from the final-state docs. The following items were found during the alignment pass and are flagged for an incremental cleanup; the canonical choice is already stated in the final-state docs (Architecture Principles, Glossary).

Finding Canonical (final-state) Legacy occurrences Action
Agent runtime Microsoft Agent Framework (Microsoft.Agents.AI.*) + Microsoft.Extensions.AI Residual Semantic Kernel / SK terminology in legacy spec pages ✅ RESOLVED — bulk-normalized to Agent Framework, Microsoft.Extensions.AI, and MCP across agents/, platform-architecture/, templates-docs/, and related pages. ADR-0002 retains Semantic Kernel only as the rejected alternative.
IaC tool Pulumi (.NET/C#) "Bicep" appears in platform-architecture/*, core-principles/cloud-native-mindset.md, agent specs, factory/runtime/control-plane.md Reframe Bicep as legacy alternative only; new IaC is Pulumi. Final-state DevOps docs already do this.
Knowledge naming Knowledge Platform (alias: "Knowledge Fabric") "Knowledge Fabric" / "Knowledge and Memory System" in platform-architecture/* Alias recorded in glossary; hub pages now link to the Knowledge Platform.
Backend version .NET 10+ residual ".NET 8/9" in some specs ✅ RESOLVED — normalized to .NET 10+ across documentation.
gRPC contracts Code-first C# (ServiceModel.Grpc, no .proto) Proto/protobuf as default for internal gRPC ✅ RESOLVED — internal gRPC documented as code-first; .proto reserved for foreign-stack anti-corruption adapters only.

Note

Bicep and a few foreign-stack .proto references remain where they describe legacy or non-ConnectSoft integrations. The authoritative final-state stack is defined in AI Software Factory Glossary and Architecture Principles.

Terminology and Naming

Inconsistencies

AI Factory Docs Company Docs Issue Resolution Needed
"AI Factory" "AI Software Factory" Inconsistent naming Standardize on "AI Software Factory"
"Factory" "AI Software Factory" Abbreviation usage varies Define when abbreviation is acceptable
"Blueprint" "Blueprint" Generally consistent No action needed
"Agent" "AI Agent" Sometimes inconsistent Standardize on "Agent" or "AI Agent" consistently
"Semantic Kernel" "Microsoft Agent Framework" / "Microsoft.Extensions.AI" Technology stack terminology ✅ RESOLVED - Replaced across agent specs, platform architecture, and template docs
".NET 8/9" ".NET 10+" Version references ✅ RESOLVED - Updated to .NET 10+ throughout documentation
"Core Platform" "Core Platform" Terminology consistency ✅ RESOLVED - Now consistently used across vision documents
"SaaS Cycles" "SaaS Cycles (1-5)" Terminology consistency ✅ RESOLVED - Now consistently referenced in strategic goals
"4 Pillars" / "Four Pillars" "Four Product Pillars" Terminology consistency ✅ RESOLVED - Now consistently referenced in vision documents

Architecture and Design

Template Architecture

Issue: AI Factory docs reference template architecture from starters documentation, but some details may not align with company documentation.

Location: - AI Factory: templates-docs/template-architecture.md - Company: ConnectSoft.Documentation/Docs/starters/template-architecture-specification.md

Status: ✅ RESOLVED - All extended templates have been aligned to the three-layer DI model using MicroserviceRegistrationBase hooks. templates-overview.md now includes a DI alignment status section. The base-template-di-extensibility.md docs in both public and company repos have been updated with the extended template registration classes, override strategies, Program.cs Serilog bootstrap pattern, and migration checklist.

Platform Architecture

Issue: Company documentation may have different emphasis on certain architectural patterns.

Location: - AI Factory: platform-architecture/overall-architecture.md - Company: Various architecture documents

Status: Needs review

Roadmap and Timeline Alignment

Timeline Start Dates

Issue: All roadmaps should start from January 1, 2026.

Status: ✅ RESOLVED - All roadmap documents and strategic goals now start from January 1, 2026. Time horizons in strategic-goals.md are properly aligned with company documentation.

Roadmap Phases

Issue: Company documentation may have different phase definitions or timelines.

Location: - AI Factory: roadmap/short-term-plan.md, roadmap/mid-term-expansion.md, roadmap/long-term-platform-evolution.md - Company: roadmaps/factory-roadmap.md

Status: Needs review for alignment

Agent Specifications

Agent Naming and Roles

Issue: Some agent names or roles may differ between AI Factory docs and company docs.

Location: - AI Factory: agents/detailed-agent-specifications/*.md - Company: Various agent references

Status: Needs review

Database Architect Naming Gap

Issue: Company documentation referenced a "Database Architect" role but no corresponding agent existed in the AI Factory agent registry. The role was ambiguous between architecture-level database design and hands-on database engineering.

Status: ✅ RESOLVED - The Database Engineer Agent has been added to the Software Engineering cluster. This agent covers schema design, migration scripts, and database optimization — aligning the AI Factory agent registry with the company documentation's intent for database-focused automation.

Incubator Agent Registry Gap

Issue: Several agent concepts referenced across planning documents and incubator discussions were not registered in the agent cluster tables, mesh topology, or system component documentation. This created a gap between planned agent capabilities and documented architecture.

Status: ✅ RESOLVED - 27 new agents have been added across all platform architecture documentation (agentic-system-design.md, system-components.md). New clusters added: UX/UI, Security, Observability, Documentation, Growth, and Platform Evolution. All agents are now registered in cluster tables, execution group listings, and mesh topology diagrams.

Agent Capabilities

Issue: Agent capabilities and skills may be described differently.

Status: Needs review

Template Documentation

Template Availability

Issue: AI Factory docs may reference templates that don't exist or have different names in company docs.

Location: - AI Factory: templates-docs/*.md - Company: ConnectSoft.Documentation/Docs/starters/*

Status: Needs review

Template Parameters

Issue: Template parameters may differ between documentation sets.

Status: Needs review

Workflow Documentation

Workflow Definitions

Issue: Workflow definitions may differ between AI Factory and company documentation.

Location: - AI Factory: workflows/*.md - Company: Various workflow references

Status: Needs review

Vision and Strategy

Strategic Goals

Issue: Strategic goals may be worded differently or have different emphasis.

Location: - AI Factory: vision/strategic-goals.md - Company: factory/strategic-goals.md

Status: ✅ RESOLVED - Strategic goals document has been enhanced with: - Core Concepts section (Core Platform, Templates, SaaS Cycles) - Strategic Themes section mapping 10 goals to 4 themes - Time Horizons section (Short/Mid/Long term starting January 2026) - Alignment with Business Strategy section - OKR-style key results - Enhanced introduction explaining Factory's role in ConnectSoft strategy

Vision Statements

Issue: Vision statements may have different wording or emphasis.

Location: - AI Factory: vision/vision-overview.md - Company: Various vision documents

Status: ✅ RESOLVED - Vision overview document has been enhanced with: - Factory's role in ConnectSoft's 4-pillar portfolio section - "Factory in the ConnectSoft Ecosystem" section - Strategic Moat section explaining knowledge system and accumulated assets - Factory's role in 5-cycle strategy section - Enhanced "What Makes It AI-Driven?" section aligned with company vision

Platform Foundations

MCP Servers

Issue: MCP server documentation may have different details or emphasis.

Location: - AI Factory: archive/connectsoft-mcp-servers-catalog.md - Company: Various MCP references

Status: Needs review

Content Gaps

Missing Documentation

Issue: Some topics covered in company documentation may be missing from AI Factory docs.

Areas to Review: - Business model details - Pricing and licensing - Partner program - Customer onboarding process - Support processes

Status: Needs review

Incomplete Documentation

Issue: Some AI Factory docs may be incomplete compared to company documentation.

Areas to Review: - Template architecture details - Agent implementation specifics - Workflow execution details - Studio features

Status: Needs review

Solution Misalignments

Technical Approach

Issue: Technical approaches may differ between documentation sets.

Areas to Review: - Template composition approach - Agent execution model - Orchestration patterns - Observability implementation

Status: Needs review

Implementation Details

Issue: Implementation details may differ or be missing.

Areas to Review: - Runtime architecture - State management - Failure handling - Recovery mechanisms

Status: Needs review

Recommendations

Priority Actions

  1. High Priority:
  2. ✅ Align terminology and naming conventions (Partially resolved - Core Platform, SaaS Cycles, 4 Pillars now consistent)
  3. ✅ Review and align roadmap timelines and phases (Resolved - All timelines start from January 1, 2026)

  4. Verify template architecture alignment

  5. Medium Priority:

  6. Review agent specifications for consistency
  7. Align workflow definitions

  8. ✅ Verify vision and strategy alignment (Resolved - Strategic goals and vision documents aligned)

  9. Low Priority:

  10. Fill content gaps
  11. Complete incomplete documentation
  12. Review solution misalignments

Review Process

  1. Identify Inconsistencies: Use this document as a starting point
  2. Verify Against Source: Check company documentation for authoritative source
  3. Update AI Factory Docs: Align AI Factory documentation with company documentation
  4. Mark as Resolved: Update this document when inconsistencies are resolved