docs(debug-logger): refresh stale info after first deploy + establish AGENTS.md convention#43
Merged
Merged
Conversation
… AGENTS.md convention Two motivations: 1. The autonomous build's docs were written before any of the POC artifacts had been deployed to a tenant. The first deploy (PR #42) discovered 8 bugs and surfaced 6 documentation drifts that this PR fixes. Without these refreshes, future AI agents reading the docs would replicate the same fabricated APIs, missing colliding columns, and the wrong solution layout. 2. The repo previously had no AGENTS.md convention — only .github/copilot-instructions.md at root. Establishing per-solution AGENTS.md (terse, AI-context-optimized) gives contributors a dedicated companion to the human-facing README that documents critical constraints, known issues, schema- prompt-code contract, and 'where to look first when something breaks' diagnostics. Stale-info fixes (per-file): - copilot-agent-debug-logger/README.md * File Map updated to Microsoft-canonical layout (src/Solutions/ src/Entities/, AppModules/, AppModuleSiteMaps/, etc.) replacing the obsolete Frank R2 scaffold shape (Solution.cdsproj + other/ + CanvasApps/.gitkeep). Added a layout note explaining the restructure. * cr_payload truncation reference: left(string(...)) → substring() with min()/length() (WDL-native; left() is Power Apps Canvas). * cr_sourcename data-contract row marked '_documented but not stored_' with pointer to Known Issues. * 'No managed-solution ALM' line: Solution.cdsproj → CopilotAgentDebugLogger.cdsproj * NEW 'Known Issues (deploy-time discoveries)' section with 6 items: cr_sourcename collision, env-var yes/no storage, PVA tool flow Action-add requirement, Phase-0 nested clone layout, UniqueIdentifier rejection, PAC CLI 2.x list-environments drop. Each cites its backlog todo. - copilot-agent-debug-logger/docs/phase-0-mda-authoring.md * Step 3 expected result: legacy CanvasApps/AgentDebugConsole_* path → src/Solutions/src/AppModules/cr_AgentDebugConsole/. * Step 5 cr_sourcename form-field item: noted as unwritable with pointer to Known Issues. * Sample precheck PowerShell: Get-ChildItem -Directory → Test-Path -PathType Container (correctness fix from PR #42). - copilot-agent-debug-logger/docs/maker-guide.md * Data-contract cr_sourcename row updated. * Payload-truncation pattern (Quick Start + Pattern A Common Setup + Pattern A truncation reminder) updated to WDL substring(). * Pattern C/D smoke-test row expectations: cr_sourcename = ... → cr_tracelabel begins with COPILOT_TOPIC/CoT @ or COPILOT_TOPIC/ConversationHistory @. - copilot-agent-debug-logger/docs/deployment-guide.md * Step 2 expected-source-state snippet: Get-ChildItem -> Test-Path -PathType Container; legacy CanvasApps path -> new src/Solutions/src/AppModules path. * Step 4 build description: Solution.cdsproj -> CopilotAgentDebugLogger.cdsproj. * Pattern C/D row-value expectations rewritten to match cr_tracelabel encoding. * Validation-checklist MDA-artifacts path updated to canonical layout. - copilot-agent-debug-logger/scripts/deploy-solution.ps1 * .SYNOPSIS / .DESCRIPTION / .PARAMETER docstring updated to mention the *.cdsproj auto-discovery glob (the script logic was already correct per PR #42; this catches the help text up). - .github/copilot-instructions.md * POC Constraints A15 entry updated: left() -> substring(...). * D7 MDA constraint updated: CanvasApps -> src/AppModules layout. * NEW 'Known issues from first deploy (PR #42)' bullet expanding the POC Constraints section with the 6 deploy-time discoveries. * NEW 'Per-solution AGENTS.md convention' section between Planning Structure and POC Constraints — discoverability for AI agents. Newly created: - copilot-agent-debug-logger/AGENTS.md (153 lines) — establishes the convention. Sections: Mission, Stack, Commands, File map, Critical constraints (A1/A2-D3/A3-D4/A4/A9/A15/D1/D2-A5-A6/D5-B1/D6/D7/D8/D15), Schema-prompt-code contract, Known issues table with workarounds and follow-up backlog refs, Operational sequence, IWL reference precedents, Don't list, Where to look first when something breaks table, Cross-references. Template for the other 3 solutions per backlog todo agentsmd-other-solutions. Verification: - All 4 .topic.mcs.yml YAMLs still parse via python yaml.safe_load - Both flow JSONs parse via JSON.parse - Schema JSON parses + still has 13 columns - deploy-solution.ps1 + provision-environment.ps1 still parse via PS AST - Repo grep for stale refs: only intentional 'legacy X -> new Y; see PR #42' historical references remain - PII scan: clean (only example.com / placeholder GUIDs across touched files) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two motivations:
Autonomous build docs were written before any artifact was deployed. The first deploy (PR fix(debug-logger): 8 deploy-time hot-fixes from first smoke test (Jude Dev) #42) discovered 8 bugs and surfaced 6 documentation drifts this PR fixes. Without these refreshes future AI agents reading the docs would replicate the same fabricated APIs / wrong layout.
Repo had no AGENTS.md convention — only
.github/copilot-instructions.mdat root. Establishes a per-solution AGENTS.md companion (terse, AI-context-optimized) starting with copilot-agent-debug-logger; backlog todoagentsmd-other-solutionscovers IWL, EPA, and cost-governance follow-ups.Files changed
copilot-agent-debug-logger/README.mdcopilot-agent-debug-logger/docs/phase-0-mda-authoring.mdTest-Path -PathType Containercopilot-agent-debug-logger/docs/maker-guide.mdcopilot-agent-debug-logger/docs/deployment-guide.mdcopilot-agent-debug-logger/scripts/deploy-solution.ps1.github/copilot-instructions.mdcopilot-agent-debug-logger/AGENTS.mdAGENTS.md sections
Mission · Stack · Commands · File map · Critical constraints (A1/A2-D3/A3-D4/A4/A9/A15/D1/D2-A5-A6/D5-B1/D6/D7/D8/D15) · Schema-prompt-code contract · Known issues with workarounds and follow-up backlog refs · Operational sequence (first-time deploy) · IWL reference precedents · Don't list · "Where to look first when something breaks" diagnostic table · Cross-references
Verification
*.topic.mcs.ymlparse viapython -c yaml.safe_loadJSON.parsedeploy-solution.ps1+provision-environment.ps1still parse via PS ASTPending backlog (added as SQL todos in coordinator session)
rename-cr-sourcename— proper fix for the Picklist Virtual collisionboolean-envvar-tolerance— make Compose_EnabledFlag accept yes/true/1productionize-deploy-flows-script— harvest ad-hoc Flow Mgmt API scripts intoscripts/deploy-flows.ps1configure-mda-views— Recent Traces / Timeline by Correlation ID / Errors Only views + multiline form layoutadd-tool-flow-action-cs— add tool-log-agent-trace as Action on a consumer agent (only way to materialize the PVA flow)agentsmd-other-solutions— add AGENTS.md for IWL, EPA, cost-governance using debug-logger as template