traxxall-standards

Backing references

Load these on demand rather than from memory:

• kb/traxxall-platform-overview.md — platform facts, Azure services, deployment slot SOP.
• kb/cicd-qa-deployment-ado.md — ADO delivery process, sprint model, WI types, hotfix workflow, Vlad's role.

---

Branch naming

Allowed prefixes

Prefix	Used for
users/	Individual developer feature/fix branches (most common)
fixes/	Hotfixes and targeted repair branches
features/	Large feature tracks (rare)
releases/	Release and deployment branches

Pattern for developer branches

users/{shortname}/{WI#}-{description}

• {shortname}: developer's short name or alias (e.g., sbenson, vlad).
• {WI#}: the ADO work-item number (integer, no hash symbol in the branch name itself).
• {description}: kebab-case summary, lowercase, hyphens only, no spaces.

Examples of valid branch names:

• users/sbenson/16472-admin-query-perf
• users/vlad/16500-universalapi-compliance-fix
• fixes/16510-hotfix-portal-null-ref

VS403660 — prefix rejection

The ADO repository policy rejects any push to a branch whose name does not start with one of the four allowed prefixes. This surfaces as error VS403660.

When linting a branch name:

1. Extract the prefix (everything before the first /).
2. Check it against the allowed list.
3. If not in the list — REJECT. Emit the VS403660 rationale and propose the corrected form.

Example rejection:

• Input: perf/admin-query-fix
• Verdict: REJECTED — perf/ is not an allowed prefix (VS403660).
• Corrected form: users/{shortname}/{WI#}-admin-query-fix

Never silently accept a non-compliant branch name. Never propose a branch name that would fail VS403660.

---

Commit discipline

• Every commit message must reference a work-item number. Format: include #WI-{number} or the ADO AB#{number} link syntax somewhere in the message.
• The PR-validation pipeline enforces WI linkage. A commit without a WI reference will cause the pipeline to fail.
• Keep commit messages descriptive: one line summary, optional body for context.

---

PR discipline

Every PR must:

1. Link to a work item (set the ADO link in the PR, not just in the commit message).
2. Pass the PR-validation pipeline (build gate + WI linkage check).
3. Include these sections in the PR description:
   • Summary — what changed and why.
   • Related WI — ADO work-item number(s) with links.
   • Business/Technical Reason — the motivation.
   • Files/Components Affected — list changed projects and files.
   • Test Cases to Validate — what to verify (observable behaviour, not method names).
   • Known Risks/Follow-ups — anything that might regress or needs further work.

---

Work-item model

Types in use

• PBI (Product Backlog Item): new capability, enhancement, or hotfix container.
• Bug: regression or defect. Same hierarchy as PBI.
• Task: child of PBI/Bug; carries the developer branch and the concrete implementation unit.

Epics, Features, and User Stories are NOT used in this ADO project. Do not create them. Do not reference them in output.

Hierarchy

PBI | Bug
  └─ Task (carries the branch; one per developer/component)
       └─ QA ticket (owned by PH QA team — never author this from the dev side)
            └─ Issue/failure tickets (QA-generated)

Area path

Always: Traxxall Solution (verbatim, no sub-paths).

Tags — segmentation model

Use tags, not area sub-hierarchy, to segment items:

Tag	Meaning
AI First	AI-generated or AI-authored item
AI Assist	AI-assisted (human-authored with AI help)
360	Product: Traxxall 360
Admin	Product: admin.traxxall.com
Portal	Product: Portal
Inventory/MMS	Product: Inventory / MMS
MRO	Product: MRO
Scheduler	Product: Scheduler

Multiple product tags are allowed. Always include AI First on any AI-authored item.

Sprint naming and model

• Sprints are one week, Saturday–Friday, no gaps.
• Sprint name = the Friday end date in ISO format: YYYY-MM-DD (e.g., 2026-07-04).
• Sprints roll up under quarterly parent iterations: Q3 2026, Q4 2026, etc.
• When assigning a sprint, use the current sprint (if work starts this week) or the next sprint (if not starting until next week). Never assign a past sprint.

Custom statuses

Status	When to apply
Requires Specification	Requirements unclear — note exactly what is missing.
Waiting for Specs	Specification is started but awaiting additional detail.
Ready to Test	Full item ready for PH QA team review.
Ready to Test Partial	Part of a larger feature ready for QA; remainder still in progress.
Testing Failed	QA found issues; dev must fix and re-submit.
Deferred Deployment	Unscheduled; not for immediate deployment.

Hotfix traceability

Hotfix items carry an HF designation in the title. They flow:

1. Zendesk ticket → ADO PBI (HF) → child Task → cherry-pick to release branch → deploy affected products.
2. The WI must record: hotfix version number, target branch name, and affected products.
3. Zendesk ↔ ADO ↔ Git ↔ release branch ↔ deployed version must remain traceable through links and comments.

---

Dual-framework table

Every skill that touches code areas must declare which framework world the change lives in.

World	Projects	DI pattern	DbContext
Legacy .NET Framework 4.x	Traxxall.Web, Traxxall.Admin, Traxxall.WebApp, Traxxall.WebApi	ServiceLocator.Current.GetInstance<T>()	EF6; may be resolved ad-hoc via ServiceLocator
Modern .NET Core 6/7	Traxxall.NETCore.WebApi, Traxxall.v2.UniversalAPI, Traxxall.Core.OAuth	Constructor DI	Injected by DI; read-replica opt-in is a constructor bool
Shared core	Traxxall.Core, Traxxall.Models, Traxxall.v2.Infrastructure*	Consumed by both	Changes propagate to both API surfaces

Blast-radius rule: any change to shared core projects must be flagged as high blast-radius in specs, intake briefs, and task descriptions. Add a standards_notes entry: "Shared core touch — changes propagate to both Legacy and Modern API surfaces. Review all consumers before merging.".

---

Draft-vs-create discipline

• Default is always draft. Every skill produces a paste-ready draft that the user can review, edit, and submit manually.
• Vlad creates approximately 95% of backlog items and is the delivery hub. AI-authored items must defer to his review.
• Create on explicit go only. The traxxall-pbi-author and traxxall-task-decomposer skills escalate to ADO creation ONLY when:
  1. The user's message contains an explicit create instruction (e.g., "create it", "go ahead and create", "push this to ADO").
  2. The traxxall-ado-auth skill confirms a Work-Items-write PAT scope is available.
  3. All required fields (area path, iteration, title, description, tags) are fully populated.

---

Auth and egress mechanics

• PAT retrieval: use the traxxall-ado-auth installed skill. It retrieves the ADO PAT from macOS keychain via security find-internet-password. Never hardcode a PAT or embed it in a command string.
• Named remote: use the named remote configured for dev.azure.com to bypass egress guardrails. Never construct git push commands with literal blocked-host URLs.
• ADO REST and az commands: always target dev.azure.com/{org}/{project}. Never use visualstudio.com or vsrm.visualstudio.com.
• Call pattern: every skill that issues az boards, az repos, git push, or ADO REST calls must invoke traxxall-ado-auth first.

---

CI pipeline reality

Pipeline	Trigger	What it does
PR validation	Every PR	Build gate + WI linkage check. This is the build gate — no local build is required before opening a PR.
Merge / model propagation	Merge to main	Full CI build + TypeScript model generation + artifact commit back to main.
Veracode security scan	Scheduled	Security scan. Developers do not need to interact with this directly.

No local build required. Never instruct the user to build locally before opening a PR. The PR-validation pipeline is the gate.

No CD. Deployments are manual, slot-based, with warm-up required. Never include a deployment step in a task or spec without explicitly noting it is a manual operation.

---

Dev test boundary

• Author-side tests: use UnitTests.Core patterns with TransactionScope rollback. Every database operation is wrapped in a TransactionScope that is never committed, so the test leaves no persistent state.
• Destructive utility projects: the existing "unit test" projects in the repo (e.g., cache manipulation, mock data population utilities) may corrupt data. Never auto-run them. Never wire them into CI.
• The traxxall-dev-tests skill writes tests; it does not run them. Execution is the developer's responsibility after manual review.
• QA test authoring is out of scope. The blind adversarial QA plugin (separate, not installed here) handles Playwright/QA tests. Never generate QA test content or share developer test context with the QA plugin.

---

Lint mode

When invoked in lint mode (task type standards_lint), apply these checks:

1. Branch name lint: extract prefix, check against allowed list, reject non-compliant names with VS403660 rationale and corrected form.
2. PR description lint: check for all six required sections (Summary, Related WI, Business/Technical Reason, Files/Components Affected, Test Cases to Validate, Known Risks/Follow-ups). Flag any missing section.
3. WI field lint: check that area path is Traxxall Solution, at least one product tag is present, AI First tag is present if AI-authored, and an iteration is assigned.
4. Commit message lint: check for WI reference (AB# link or #WI- reference).

Return a lint verdict: PASS or FAIL with the specific issues listed. For FAIL, always include the corrected form.