Fix docker-compose credential corruption and blank local database credentials

[Alex Weininger (alexweininger)]

Problem

Reference docs under resources/ inlined concrete credentials — for example a literal DATABASE_URL: postgresql://user:password@host:5432/db. The azure-debug-generate skill then wrote the same shape into generated local dev files such as docker-compose.yml. This produced two distinct failure modes.

1. Fatal YAML corruption

A secret-redaction filter rewrites the credential literal to a masked value. In YAML a leading * is an alias indicator, so the moment a redacted value lands in docker-compose.yml the file stops parsing entirely.

This is why redaction is fatal here rather than merely cosmetic: the masked text isn't just an unusable value, it's a syntax error. Local dev is dead on arrival, and the error the user sees points at YAML syntax — not at the credential that caused it.

2. Silent blank credentials

Where compose did use ${POSTGRES_USER} / ${POSTGRES_PASSWORD}, the skill often generated no workspace-root .env. Docker Compose interpolates ${...} from .env or the shell environment — never from a service's own environment: block. With no .env, the variables resolve to empty strings and Postgres starts with blank credentials, producing auth failures that look like application bugs.

Fix

The guidance now:

• Declares local credentials once in a workspace-root .env, and references them via ${...} everywhere else.
• Forbids inlining a concrete user:password@host URL into any generated file, and explains the YAML-alias rationale so the rule isn't mistaken for style advice.
• Requires .env to exist and to declare every variable compose references — including a note that .env.example is documentation only and nothing loads it.
• Documents which host to use in a connection string: localhost for clients running on the host machine (VS Code debug target, npm task) vs. the postgres service name for clients running inside compose.
• Notes that local.settings.json is plain JSON with no ${...} interpolation, and that a runtime settings file does not cover host-run tasks such as npm run db:migrate.

.env must be gitignored, and secrets belong in no commit

Per review feedback: the guidance told the agent to create a workspace-root .env holding real credential values, but never said it must be ignored.

.gitignore must now list .env before the file is created, stated at each point where it actually gets written (emulators/postgres.md, references/generate.md), with an explicit instruction to fix a missing or incomplete .gitignore first. shared-references/architecture.md § .gitignore Additions carries the rule in full, since that section defines the generated .gitignore contents: a secret that reaches a commit is compromised the moment it is pushed, deleting it in a later commit does not undo that because the value stays in history and in every clone and fork, recovery means rotating the credential rather than editing a file, and private repositories are no exception.

azure-project-scaffold/instructions.md makes the ordering explicit — .gitignore is written in Step 2 (Foundation), before Step 3 (Configuration & Environment) creates env files.

Audit: no reference doc can seed a masked value

The remaining reference docs carrying a concrete credential literal are fixed too. This matters because a reference doc is read by the agent before it writes anything — the literal is masked in the agent's context by secret redaction and then transcribed verbatim into the generated project. All concrete credential literals under resources/ are now eliminated, so no reference doc can seed a masked value into a generated project.

• azure-project-plan/plan.md — the two connection-string table rows are templates the planning agent fills in, so a masked value propagates into .azure/project-plan.md and downstream into generated code. Highest-impact of the set.
• shared-references/resilience.md and shared-references/service-abstraction.md — the sample test setup now builds the URL from process.env via a template literal (quoting changed from single quotes to backticks accordingly).

Verified with git grep -lE '://[A-Za-z0-9_.-]+:[A-Za-z0-9_.!$-]+@' HEAD -- resources/ → zero files.

Files changed

• resources/agents/azure-debug-generate/references/emulators/postgres.md
• resources/agents/azure-debug-generate/references/generate.md
• resources/agents/azure-project-plan/plan.md
• resources/agents/azure-project-scaffold/instructions.md
• resources/agents/shared-references/architecture.md
• resources/agents/shared-references/resilience.md
• resources/agents/shared-references/runtimes/python.md
• resources/agents/shared-references/runtimes/typescript.md
• resources/agents/shared-references/service-abstraction.md

Markdown instruction files only — no extension source changes, nothing to compile.

Related

The accompanying evaluation-system detection for this defect ships separately in #1669.

[Alex Weininger (alexweininger)]

I ran into this while testing. Verified that my change does fix it. However, I am worried that what Copilot wrote here is too verbose

[Matthew Fisher (MicroFish91)]

LGTM

I ran into this while testing. Verified that my change does fix it. However, I am worried that what Copilot wrote here is too verbose

Yeah I noticed this too. I think it's because it's reiterating the same reminders across multiple agents. Ideally I would just like the agent responsible for creating the .env the first time to add it to .gitignore and not have to keep reiterating / reminding the later agents about it. In practice though I know an agent could accidentally skip and I could see the benefit of having those reminders as fallbacks in later phases, but that does come at the cost of instruction bloat.