The Atlas MikeOSS.Azure's docs, bound to the code — and to the migration that built it
108 documents
docs/migration/session-2026-05-08-to-10.md

Session summary — 2026-05-08 → 2026-05-10

Internal-only working notes covering three days of migration, QA, and follow-up work across the three Mike-Azure repos. This file lives in docs/migration/ and is excluded from publication to either target by the existing tier rules.

Repos in play

Role Local path Remote
Source of truth (private, internal) C:\Data\Projects\MikeAzureDev not pushed publicly
Public AGPL fork C:\Data\Projects\MikeOSSAzure Altien/mikeOssAzure
Private deploy / marketplace repo C:\Data\Projects\MikeAzureDeploy Altien/MikeAzureDeploy

Topology is also recorded in the auto-memory file project_three_repo_topology.md.

What got done

1. Initial migration to MikeOssAzure and MikeAzureDeploy (2026-05-08)

Reviewed docs/migration/ plan, then migrated MikeAzureDev's diverged tree to the two publication targets. Policy was "commit locally only, hard compile requirement per commit".

  • MikeOssAzure received 19 commits on top of the upstream baseline b780a4b (= MikeOssAzure's initial empty commit d969096):
    • 2 Tier-A small refactors (storage interface, auth interface) — cherry-pickable for upstream PRs to willchen96/mike.
    • 17 Tier-B feature commits grouped by logical scope: KV config, Azure Blob, schema migrations, Entra + tenant lifecycle, local HS256, user profile REST, OpenAI/AOAI, JSONB fix, supabase wrapper + chat fallback, install configurator + diagnostics, runtime /config + bundled frontend, env example, frontend ConfigContext + AuthContext, SSR shells, Dockerfile, local-stack, docs.
  • MikeAzureDeploy received 8 commits on top of the empty initial commit:
    • Bicep templates, deploy scripts, install operator scripts, CI/supply-chain scripts, runbooks/infra docs, README rewrite.

Both passed the per-commit tsc --noEmit and the sanitisation regex for tenant identifiers (Entra GUIDs, dev FQDN, *-mike-{dev,prod} resource names).

2. Acknowledgements + provenance (2026-05-09)

Added a structured Acknowledgements section to MikeOssAzure/README.md naming the upstream as willchen96/mike (commit b780a4b), plus scaffolding for future merged-from-upstream and merged-from-other-fork entries. Memory rule feedback_acknowledgements_links.md codifies the requirement that every upstream-derived change links to the source commit/PR (or to a docs/extractions/<name>.md for messy multi-commit extractions).

3. SECURITY.md and CONTRIBUTING.md (2026-05-09)

Added both at the root of MikeOssAzure:

  • SECURITY.md — private vulnerability reporting policy, contact security@altien.com.
  • CONTRIBUTING.md — branching, commit shape, sanitisation rules, provider-boundary rules, "consider contributing upstream first" guidance, and a placeholder testing section noting the suite is on the roadmap.

4. Microsoft Marketplace TTK validation (2026-05-10)

User submitted a build to Microsoft Marketplace. Microsoft's arm-ttk returned five 300.4.1.1 Best Practice Tests failures:

  1. deploymentTemplate_Location Should Not Be Hardcoded — infra/main.bicep:23 has param location string = 'westeurope'. Should be param location string = resourceGroup().location.
  2. CreateUIDefinition_Password Textboxes Must Be Used For Password Parameters — mainTemplate.json securestrings collected via TextBox instead of PasswordBox.
  3. CreateUIDefinition_Credential Confirmation Should Not Be Hidden — at least one PasswordBox has hideConfirmation: true.
  4. CreateUIDefinition_Outputs Must Be Present In Template Parameters — drift between createUiDefinition outputs and mainTemplate parameters.
  5. CreateUIDefinition_Allowed Values Should Actually Be Allowed — dropdown allowedValues don't match parameter allowedValues.

Status

  • The Bicep location default fix is identified but not yet applied — this is a Tier C change, lands in MikeAzureDeploy only.
  • The four createUiDefinition.json issues need the actual marketplace package files which weren't located in the tree at scan time. Three options on the table for the user: point at where the package was assembled, paste the JSON files, or scaffold them fresh.
  • A planned scripts/qa/run-ttk.ps1 would compile Bicep → mainTemplate
    • run Test-AzTemplate over the marketplace package. Not yet written.

Workflow agreed

Fix in MikeAzureDev → test → migrate the fix to MikeAzureDeploy. The TTK fix is Tier C and does not propagate to MikeOssAzure.

5. Architecture-leakage cleanup + QA (2026-05-10)

The session's biggest shift. After confirming the topology hasn't changed, the user surfaced a constraint that hadn't been explicit earlier: OSS-shipped docs and code must describe what the fork does, never what was removed or where the removed parts live. Words like marketplace, Tier C, Repo 3, MikeAzureDeploy, private deploy, deploy package, [link to marketplace listing] all leak the existence and shape of the deploy-side IP.

Audit on MikeOssAzure found 50 leaks. Triaged and cleaned:

Same edits applied in MikeAzureDev so the next migration produces a clean OSS without re-doing the work.

QA scripts (scripts/qa/)

  • check-leakage.ps1 — forbidden-phrase scan over file content and the last N commit messages. Defaults to git-tracked files only; -SourceMode skips internal-only paths (docs/migration/, infra/, deploy.ps1, .claude/, README.md, docs/agent-handoff.md, the Tier C issue subset). -CommitDepth N controls commit-scan depth (default 50). -SkipCommitScan and -IncludeUntracked are escape hatches.
  • check-no-tier-c-in-oss.ps1 — path-based check that no Tier C file (Bicep, deploy.ps1, install operator .ps1, deployment runbooks, Tier C issue docs, docs/migration/) exists in the public-fork tree.
  • scripts/qa/README.md — usage notes and where each script fits in the publication workflow.

Category error captured for future sessions

The first leakage-cleanup commit (ced05d7 in MikeOssAzure, before amend) had clean file content but a commit message that enumerated every "Altien Marketplace package", "Tier C", "Repo 3", "downstream marketplace" phrase being removed — exactly the leak the file-level cleanup was preventing. Caught and amended to edbd532 before push. The QA script's commit-message scan was added in response.

Three earlier MikeOssAzure commits (feec6d3, 0bf51f7, c94bf9f) were already pushed with leaky messages and remain in the public log. User chose to accept the historical leakage rather than force-push a rewrite.

Memory feedback_oss_no_architecture_leakage.md updated with:

  • The forbidden-pattern list.
  • The "applies to every public surface, not just file content" rule.
  • The category error and SHAs as a worked example.
  • The "describe positive shape, not negative delta" rule for leakage-cleanup commit messages.

Memory rules added or updated this session

All in C:\Users\alien\.claude\projects\C--Data-Projects-MikeAzureDev\memory\:

  • project_three_repo_topology.md — names the three repos, their roles, what lands where.
  • feedback_public_fork_push.md — commit locally on MikeOssAzure / MikeAzureDeploy; the user pushes after review. MikeAzureDev not subject to this rule.
  • feedback_acknowledgements_links.md — every upstream-derived merge in MikeOssAzure/README.md Acknowledgements needs a direct GitHub URL (commit / PR / extraction note).
  • feedback_oss_no_architecture_leakage.md — the leakage rule, with the commit-message-leak addendum and category-error example. Lives in MikeAzureDev memory regardless of which repo is being worked on.

AGENTS.md in MikeAzureDev gained a "Storage Provider Boundary" section preserving the requireProvider vs optional-chaining lesson from internal commit history (efdb687 introduced silent uploads via await _provider?.upload(...); 2dbce7c fixed it). Migrates to MikeOssAzure cleanly.

Outstanding work (open follow-ups)

  1. Marketplace TTK fixes (Workstream 1). Five createUiDefinition / mainTemplate failures still pending. Need either the existing marketplace package files or a scaffold-from-scratch decision. infra/main.bicep:23 location-default fix is the only one confirmed actionable so far.
  2. scripts/qa/run-ttk.ps1 — planned third QA script. Compiles Bicep → mainTemplate, imports arm-ttk, runs Test-AzTemplate pre-Marketplace-submission.
  3. GitHub Actions wiring for QA — both leakage scripts as a CI gate on PRs to Altien/mikeOssAzure. Workflow file not yet written.
  4. Test suite — promised in MikeOssAzure/CONTRIBUTING.md "in the coming weeks" (as of 2026-05-09). No suite exists yet on either side.
  5. Three historical leaky commit messages on Altien/mikeOssAzure main (feec6d3, 0bf51f7, c94bf9f). Decision: accept and move on. If ever revisited, requires force-rewrite of public history.
  6. Untracked blog draft in MikeOssAzure docs/blog/azure-deploy-minimal.md — local-only, contains marketplace mentions, must be sanitised before any publication.
  7. infra/main.parameters.dev.json — internal dev parameters file in MikeAzureDev. Not a marketplace concern; just a reminder it carries "location": "uksouth" which is fine for internal use but is the kind of thing the -SourceMode excludes treat correctly.

Useful commands captured

# Pre-publication QA — always run before pushing the public fork:
pwsh scripts/qa/check-leakage.ps1 -Path C:/Data/Projects/MikeOSSAzure
pwsh scripts/qa/check-no-tier-c-in-oss.ps1 -Path C:/Data/Projects/MikeOSSAzure

# Source-tree QA — the one that legitimately contains the forbidden
# phrases in internal-only paths:
pwsh scripts/qa/check-leakage.ps1 -Path C:/Data/Projects/MikeAzureDev -SourceMode

# Commit-scan-only / file-scan-only escape hatches:
pwsh scripts/qa/check-leakage.ps1 -Path . -CommitDepth 100
pwsh scripts/qa/check-leakage.ps1 -Path . -SkipCommitScan