From 4e9b379e63bf52efdb159f894286e3ee354b6f9e Mon Sep 17 00:00:00 2001 From: Rishi Kumar Chawda Date: Mon, 29 Sep 2025 16:47:02 +0530 Subject: [PATCH 1/3] add mcp configuration Signed-off-by: Rishi Kumar Chawda --- .vscode/mcp.json | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .vscode/mcp.json diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 0000000..3ac540e --- /dev/null +++ b/.vscode/mcp.json @@ -0,0 +1,9 @@ +{ + "servers": { + "atlassian-mcp-server": { + "url": "https://mcp.atlassian.com/v1/sse", + "type": "http" + } + }, + "inputs": [] +} From fd4c7e4b2382df676b8e66b675d8ad856488f31f Mon Sep 17 00:00:00 2001 From: Rishi Kumar Chawda Date: Mon, 29 Sep 2025 16:56:46 +0530 Subject: [PATCH 2/3] add initial copilot instructions Signed-off-by: Rishi Kumar Chawda --- .github/copilot-instructions.md | 436 ++++++++++++++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..a597553 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,436 @@ + + +# AI-Assisted Contribution & Workflow Guide + +## 1. Purpose +Provide a precise, enforceable, repeatable, and auditable process for AI-assisted or human+AI contributions to `mixlib-authentication`. This includes: +- Structured Jira-driven development (when a Jira ID is provided) +- Branching, testing, coverage expectations (>80%) +- Expeditor + CI integration awareness +- DCO compliance (every commit signed off) +- Safe, incremental, prompt-driven execution with explicit user confirmation +- Guardrails to prevent modification of protected assets or secrets + +## 2. Repository Structure (Concise Tree) +``` +mixlib-authentication/ + Gemfile # Ruby gem dependencies (rspec, rake, etc.) + Rakefile # RSpec + style tasks (default: spec + style) + VERSION # Gem version (bumped by Expeditor) + mixlib-authentication.gemspec # Gem specification + lib/ # Runtime library source + mixlib/ + authentication.rb # Main entrypoint requiring components + authentication/ + digester.rb # Digest / hashing utilities + http_authentication_request.rb # HTTP request canonicalization/signing + null_logger.rb # No-op logger implementation + signatureverification.rb # Signature verification routines + signedheaderauth.rb # Signed header auth logic + version.rb # VERSION constant (synced by Expeditor) + version.rb # (Maintained by update_version.sh) + spec/ # RSpec tests + spec_helper.rb # RSpec setup (no coverage tool currently) + mixlib/authentication/*_spec.rb + .github/ + workflows/ # GitHub Actions CI (lint + unit tests) + lint.yml # Cookstyle/Rubocop linting on PR + push (main) + unit.yml # Windows + Ruby matrix tests (PR + push master) + CODEOWNERS # Review / ownership rules + ISSUE_TEMPLATE/ # Issue templates (if populated) + dependabot.yml # Automated dependency update config + .expeditor/ # Expeditor automation (versioning & pipelines) + config.yml # Post-merge automation: version bump, changelog, build, publish + verify.pipeline.yml # Buildkite pipeline definitions for verification + run_linux_tests.sh # Linux test bootstrap script (bundler caching) + run_windows_tests.ps1# Windows test script + update_version.sh # Syncs gem version constant after bump + CHANGELOG.md # Human-readable change history (Expeditor updates) + README.md # Project overview & docs pointer + LICENSE # Apache 2.0 (PROTECTED – do not modify) + NOTICE # Legal notices + CODE_OF_CONDUCT.md # Delegates to Chef community CoC (PROTECTED) + CONTRIBUTING.md # Delegates to Chef central contributor guide + .rubocop.yml # Style / lint config (Cookstyle + Rubocop) + .gitignore # Git ignore rules +``` + +## 3. Tooling & Ecosystem +| Aspect | Details | +|--------|---------| +| Language | Ruby (tested against 3.1 & 3.4 in CI) | +| Package Manager | Bundler (`bundle install`) | +| Test Framework | RSpec (rspec-core/expectations/mocks) | +| Style / Lint | Cookstyle (ChefStyle) + Rubocop (`rake style` / GitHub Action) | +| Automation | Expeditor (versioning, changelog, release pipeline) | +| CI | GitHub Actions (`lint`, `unit`) + Buildkite via Expeditor pipeline | +| Coverage | Not currently configured (SimpleCov recommended to ensure/measure >80%) | +| Platforms Tested | Linux (Buildkite & GitHub), Windows (Actions + Expeditor) | + +### Suggested Coverage Enablement (If Not Present) +Add early in `spec/spec_helper.rb` (AI MUST request approval before committing if absent): +```ruby +require 'simplecov' +SimpleCov.start do + enable_coverage :branch + add_filter '/spec/' +end +puts "Coverage enabled: #{SimpleCov.coverage_path}" +``` + +## 4. MCP (Jira) Integration +If a Jira ID is supplied (e.g., `ABC-123`), ALWAYS: +1. Invoke atlassian MCP server to fetch issue: + - Action Pattern: `atlassian-mcp-server.getJiraIssue(issueIdOrKey=ABC-123)` or equivalent tool invocation. +2. Parse fields: Summary, Description, Acceptance Criteria (AC), Story Points, Linked Issues, Labels. +3. Synthesize a plan block: + - Design / Intent + - Impacted Files (create/update/delete; tests to add) + - Test Strategy (unit / edge cases / negative paths) + - Risks & Mitigations + - Coverage Focus (low-coverage areas prioritized) +4. Present plan to user with explicit confirmation prompt: `Continue to implementation? (yes/no)`. +5. Do NOT write code before user approves. + +### Standard Output Structure (After Fetch) +``` +Jira Issue: ABC-123 +Summary: ... +Acceptance Criteria: + - ... +Linked Issues: ABC-101 (relates), ABC-119 (blocks) +Plan: + Design: ... + Impacted Files: [...] + Test Strategy: [...] + Edge Cases: [...] + Risks: [...] +Continue to implementation? (yes/no) +``` + +## 5. Workflow Overview (Canonical High-Level) +1. Intake & Clarify +2. Analyze Repo / Fetch Jira (if ID provided) +3. Plan Implementation +4. Confirm Plan (must be yes) +5. Implement Incrementally (small cohesive commits) +6. Add/Update Tests (ensure/raise >80% coverage) +7. Lint / Style Fixes +8. Commit (with DCO sign-off, referencing Jira ID if applicable) +9. Push & Open PR (HTML template, risk & coverage summary) +10. Apply Labels (map from Jira / context) + +Each major step ends with: +``` +Step Summary: <1–3 sentences> +Remaining Checklist: + - [x] Completed items + - [ ] Pending items +Continue to next step? (yes/no) +Recommended next prompt: +``` + +## 6. Detailed Step Instructions +### 6.1 Intake & Clarify +Prompt user: “Please provide a Jira ID (e.g., ABC-123) or a freeform task description.” + +### 6.2 Jira Retrieval (If ID Present) +Use MCP call (example placeholder): +``` +atlassian-mcp-server.getJiraIssue(issueIdOrKey=ABC-123) +``` +Never fabricate acceptance criteria. If missing, flag and request clarification. + +### 6.3 Repository Analysis +- Confirm language & frameworks (Ruby/RSpec) +- Identify target files & necessary new specs +- Determine if coverage instrumentation needed + +### 6.4 Planning +Produce: Design, Data Flow (if relevant), Impacted Files, New Tests, Edge Cases (nil/empty, invalid signatures, large headers, clock skew), Rollback Strategy. + +### 6.5 Branch Creation +Branch naming: +- If Jira: EXACT Jira key (e.g., `ABC-123`) +- Else: concise kebab-case slug (e.g., `add-digest-sha512`) + +Commands: +```bash +git checkout -b ABC-123 +``` + +### 6.6 Implementation +Guidelines: +- Small, isolated changes +- Maintain backwards compatibility unless version bump plan approved +- Add TODO comments only with linked issue reference +Protected: Do NOT alter `LICENSE`, `CODE_OF_CONDUCT.md`, `CODEOWNERS`, Expeditor config, or GitHub workflow YAML without explicit approval. + +### 6.7 Tests & Coverage +- Place tests in `spec/mixlib/authentication/` matching file naming. +- Ensure negative + boundary cases (empty headers, invalid timestamps, incorrect signature length, algorithm mismatch). +- If coverage <80% (after enabling SimpleCov), identify top uncovered lines and add focused tests. + +### 6.8 Lint / Style +```bash +bundle exec rake style +``` +Fix offenses; do not disable cops unless justified. + +### 6.9 Commit (DCO REQUIRED) +Format: +``` +(scope): short imperative summary [ABC-123] + +Body explaining rationale, risks, test additions. + +Signed-off-by: Full Name +``` +Reject / rewrite any commit lacking sign-off. + +### 6.10 Push & PR Creation +```bash +git push -u origin ABC-123 +gh pr create --title "feat: support X [ABC-123]" --body "(temp)" +``` +Then PATCH the PR body with the HTML template (below). Use `gh pr edit` if needed. + +### 6.11 PR Description (HTML Template) +```html +

Summary

+

Concise explanation of change.

+

Jira

+

ABC-123

+

Changes

+
  • List of key modifications
+

Tests & Coverage

+

Added X specs; coverage Δ: +2.3% (now 84.1%).

+

Risk & Mitigations

+

Risk: ... Mitigation: ...

+

DCO

+

All commits signed off.

+``` + +### 6.12 Labels +Apply functional + aspect + Expeditor bump labels (if version semantics needed). See Label Reference. + +### 6.13 Idempotency & Resume +If branch already exists: fetch + checkout. If PR exists: update in-place. Never duplicate PR. + +### 6.14 Post-PR Iteration +On feedback: amend or follow-up commits (still DCO-signed). Keep commits logically grouped. + +## 7. Branching & PR Standards +| Topic | Rule | +|-------|------| +| Branch Name | EXACT Jira ID or descriptive slug | +| Draft PR | Use while tests incomplete or coverage <80% | +| Ready PR | All tests passing, coverage verified, lint clean | +| Status Checks | `lint`, `unit` (matrix), Expeditor verify pipeline (Buildkite) | +| Labels | Add aspect + platform + Expeditor bump (if needed) | + +## 8. Commit & DCO Policy +MANDATORY: Final line of every commit message: +``` +Signed-off-by: Full Name +``` +AI MUST refuse to generate unsigned commits. If contributor email unknown, request it first. No automation may strip the sign-off. + +## 9. Testing & Coverage Enforcement +Commands: +```bash +bundle install +bundle exec rake spec # runs rspec suite +``` +If coverage instrumentation added: +```bash +bundle exec rspec +open coverage/index.html # manual review (macOS) +``` +Coverage Policy: +1. Target >= 80% line & branch coverage. +2. If below threshold: list worst-offending files (lowest %), propose added examples. +3. Re-run until threshold passed. + +Edge Case Checklist (Authentication Logic): +- Expired timestamp (clock skew) +- Incorrect digest algorithm specified +- Missing required header(s) +- Malformed signature (length/charset) +- Replay attempt (same nonce/timestamp if applicable) + +## 10. Labels Reference +Core Mapping Guidance: +- bug/fix → Implementation defect +- enhancement/feature → New capability +- documentation → Docs-only change +- chore/maintenance → Non-functional upkeep +- test → Test-only improvements +- ci → CI / pipeline modifications +- security → Security relevant change + +Repository Labels (Name → Description): +``` +Aspect: Documentation - How do we use this project? +Aspect: Integration - Works correctly with other projects or systems. +Aspect: Packaging - Distribution of artifacts. +Aspect: Performance - System performance concerns. +Aspect: Portability - Platform portability concern. +Aspect: Security - Security / exposure / confidentiality. +Aspect: Stability - Consistency & reliability. +Aspect: Testing - Coverage / CI quality. +Aspect: UI - Interface presentation. +Aspect: UX - User experience. +dependencies - Dependency file update. +Expeditor: Bump Version Major - Triggers major version bump. +Expeditor: Bump Version Minor - Triggers minor version bump. +Expeditor: Skip All - Skip all Expeditor merge actions. +Expeditor: Skip Changelog - Do not update changelog. +Expeditor: Skip Habitat - Skip habitat build. +Expeditor: Skip Omnibus - Skip omnibus release build. +Expeditor: Skip Version Bump - Prevent automatic version bump. +hacktoberfest-accepted - Hacktoberfest participation. +oss-standards - OSS repository standardization. +Platform: AWS - AWS platform relevance. +Platform: Azure - Azure platform relevance. +Platform: Debian-like - Debian derivatives. +Platform: Docker - Docker/container context. +Platform: GCP - GCP platform relevance. +Platform: Linux - General Linux applicability. +Platform: macOS - macOS applicability. +Platform: RHEL-like - RHEL family. +Platform: SLES-like - SUSE family. +Platform: Unix-like - Generic Unix compatibility. +``` + +## 11. CI / Expeditor Integration +### GitHub Actions Workflows +1. `lint.yml` + - Triggers: `pull_request`, `push` to `main` + - Purpose: Cookstyle/Rubocop style validation. +2. `unit.yml` + - Triggers: `pull_request`, `push` to `master` + - Matrix: Windows Server (2019, 2022) × Ruby (3.1, 3.4) + - Purpose: Unit test validation across environments. + +### Expeditor (`.expeditor/config.yml`) +On PR merge into release branch: +1. Version bump (unless skipped by label) +2. Update `VERSION` file & propagate to `lib/mixlib/authentication/version.rb` +3. Update CHANGELOG (unless skipped) +4. Build gem (if version bumped) +Promoted pipeline triggers publish to RubyGems. + +### Buildkite Pipeline (`verify.pipeline.yml`) +- Parallel steps for Ruby versions & platforms (Linux & Windows) using container executors. +- Bundler caching to `vendor/bundle`. + +## 12. Security & Protected Files +NEVER modify without explicit maintainer instruction: +- `LICENSE` +- `CODE_OF_CONDUCT.md` +- `.github/CODEOWNERS` +- Expeditor config (`.expeditor/`) +- GitHub workflow YAML (`.github/workflows/*.yml`) +- Release automation scripts +- Any secret / credential / token references + +Disallowed actions: +- Writing plaintext secrets +- Force-pushing to default branch (`master` or `main`) +- Merging PRs +- Adding large (>1MB) binary blobs + +## 13. Prompts Pattern (Interaction Model) +Every major step output MUST include: +``` +Step Summary: +Remaining Steps: + - [x] Step 1 Intake & Clarify + - [ ] Step 2 Plan ... +Continue to next step? (yes/no) +Recommended next prompt: "Proceed to with focus on ." +``` +No implicit progression: always wait for explicit `yes`. + +## 14. Environment Preparation +Prerequisites: Ruby 3.1+ (or 3.4), Bundler, Git, GitHub CLI (`gh`). +```bash +git clone https://github.com/chef/mixlib-authentication.git +cd mixlib-authentication +bundle install +bundle exec rake spec +bundle exec rake style +``` +Optional (enable coverage): add SimpleCov (see Section 3) and re-run tests. + +## 15. Idempotency & Recovery +- If branch exists locally: `git checkout ` +- If remote only: `git fetch origin && git checkout ` +- If PR exists: update via additional commits; do not recreate +- If coverage instrumentation added previously: respect existing config; do not duplicate + +## 16. Failure Handling +| Failure Type | Response | +|--------------|----------| +| Test failing | Identify spec/file; propose fix; re-run selectively | +| Lint failing | Auto-correct if safe (`cookstyle -A`), else manual patch | +| Coverage low | Highlight uncovered lines; propose targeted specs | +| Merge conflict | Present diff hunk-by-hunk; propose resolution; request confirmation | +| Jira fetch error | Ask for re-validation of ID or alternate task description | + +## 17. Validation & Exit Criteria +Completion requires ALL: +1. Plan approved by user. +2. Code changes implemented & tests added/updated. +3. Lint passes locally & in CI. +4. Coverage >= 80% (if measurable; else instrumentation guidance provided + user acknowledgment). +5. Commits DCO-signed. +6. PR opened with HTML template filled. +7. Appropriate labels applied. +8. Risk assessment documented. +9. User confirms closure: `Task complete? (yes/no)`. + +## 18. Safeguards Summary +- Do not introduce secrets. +- Do not disable tests or lower thresholds silently. +- Do not remove license headers. +- Always prompt before destructive or sweeping changes. + +## 19. Quick Reference Commands +```bash +# Create branch +git checkout -b ABC-123 + +# Install deps +bundle install + +# Run tests & style +bundle exec rake spec +bundle exec rake style + +# Commit (DCO) +git add . +git commit -m "feat(auth): improve signature parsing [ABC-123]" -m "Signed-off-by: Full Name " + +# Push & PR +git push -u origin ABC-123 +gh pr create --title "feat: improve signature parsing [ABC-123]" --body "" +``` + +## 20. Example Interaction Transcript (Pattern) +``` +User: Implement support for HMAC-SHA512 (Jira SEC-42) +AI: Fetches SEC-42, outputs plan with impacted files, test matrix, asks: Continue? (yes/no) +User: yes +AI: Creates branch SEC-42, adds minimal code scaffold, proposes tests, asks to proceed. +... +AI: PR created #123 with coverage 82.4%, labels applied. Continue to finalize? (yes/no) +``` + +--- +This document is living; propose additive improvements via PR (following all policies above). Avoid deletions or semantic weakening of guardrails. From 8edc877a5263b7bfb43ae7bc272a3eccb2bc2140 Mon Sep 17 00:00:00 2001 From: Rishi Kumar Chawda Date: Tue, 18 Nov 2025 16:37:30 +0530 Subject: [PATCH 3/3] update instructions with AI compliance guidelines - Added formatting improvements with consistent spacing after headings - Introduced new section 21: AI-Assisted Development & Compliance - Documented mandatory Jira field updates for AI-assisted work - Specified audit trail requirements for transparency - Integrated AI compliance into main development workflow Signed-off-by: Rishi Kumar Chawda --- .github/copilot-instructions.md | 119 ++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a597553..79cf598 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,7 +7,9 @@ It MUST remain stable, additive, and non-destructive. Do not remove required sec # AI-Assisted Contribution & Workflow Guide ## 1. Purpose + Provide a precise, enforceable, repeatable, and auditable process for AI-assisted or human+AI contributions to `mixlib-authentication`. This includes: + - Structured Jira-driven development (when a Jira ID is provided) - Branching, testing, coverage expectations (>80%) - Expeditor + CI integration awareness @@ -16,6 +18,7 @@ Provide a precise, enforceable, repeatable, and auditable process for AI-assiste - Guardrails to prevent modification of protected assets or secrets ## 2. Repository Structure (Concise Tree) + ``` mixlib-authentication/ Gemfile # Ruby gem dependencies (rspec, rake, etc.) @@ -60,6 +63,7 @@ mixlib-authentication/ ``` ## 3. Tooling & Ecosystem + | Aspect | Details | |--------|---------| | Language | Ruby (tested against 3.1 & 3.4 in CI) | @@ -72,7 +76,9 @@ mixlib-authentication/ | Platforms Tested | Linux (Buildkite & GitHub), Windows (Actions + Expeditor) | ### Suggested Coverage Enablement (If Not Present) + Add early in `spec/spec_helper.rb` (AI MUST request approval before committing if absent): + ```ruby require 'simplecov' SimpleCov.start do @@ -83,7 +89,9 @@ puts "Coverage enabled: #{SimpleCov.coverage_path}" ``` ## 4. MCP (Jira) Integration + If a Jira ID is supplied (e.g., `ABC-123`), ALWAYS: + 1. Invoke atlassian MCP server to fetch issue: - Action Pattern: `atlassian-mcp-server.getJiraIssue(issueIdOrKey=ABC-123)` or equivalent tool invocation. 2. Parse fields: Summary, Description, Acceptance Criteria (AC), Story Points, Linked Issues, Labels. @@ -97,6 +105,7 @@ If a Jira ID is supplied (e.g., `ABC-123`), ALWAYS: 5. Do NOT write code before user approves. ### Standard Output Structure (After Fetch) + ``` Jira Issue: ABC-123 Summary: ... @@ -113,6 +122,7 @@ Continue to implementation? (yes/no) ``` ## 5. Workflow Overview (Canonical High-Level) + 1. Intake & Clarify 2. Analyze Repo / Fetch Jira (if ID provided) 3. Plan Implementation @@ -125,6 +135,7 @@ Continue to implementation? (yes/no) 10. Apply Labels (map from Jira / context) Each major step ends with: + ``` Step Summary: <1–3 sentences> Remaining Checklist: @@ -135,54 +146,71 @@ Recommended next prompt: ``` ## 6. Detailed Step Instructions + ### 6.1 Intake & Clarify + Prompt user: “Please provide a Jira ID (e.g., ABC-123) or a freeform task description.” ### 6.2 Jira Retrieval (If ID Present) + Use MCP call (example placeholder): + ``` atlassian-mcp-server.getJiraIssue(issueIdOrKey=ABC-123) ``` + Never fabricate acceptance criteria. If missing, flag and request clarification. ### 6.3 Repository Analysis + - Confirm language & frameworks (Ruby/RSpec) - Identify target files & necessary new specs - Determine if coverage instrumentation needed ### 6.4 Planning + Produce: Design, Data Flow (if relevant), Impacted Files, New Tests, Edge Cases (nil/empty, invalid signatures, large headers, clock skew), Rollback Strategy. ### 6.5 Branch Creation + Branch naming: + - If Jira: EXACT Jira key (e.g., `ABC-123`) - Else: concise kebab-case slug (e.g., `add-digest-sha512`) Commands: + ```bash git checkout -b ABC-123 ``` ### 6.6 Implementation + Guidelines: + - Small, isolated changes - Maintain backwards compatibility unless version bump plan approved - Add TODO comments only with linked issue reference Protected: Do NOT alter `LICENSE`, `CODE_OF_CONDUCT.md`, `CODEOWNERS`, Expeditor config, or GitHub workflow YAML without explicit approval. ### 6.7 Tests & Coverage + - Place tests in `spec/mixlib/authentication/` matching file naming. - Ensure negative + boundary cases (empty headers, invalid timestamps, incorrect signature length, algorithm mismatch). - If coverage <80% (after enabling SimpleCov), identify top uncovered lines and add focused tests. ### 6.8 Lint / Style + ```bash bundle exec rake style ``` + Fix offenses; do not disable cops unless justified. ### 6.9 Commit (DCO REQUIRED) + Format: + ``` (scope): short imperative summary [ABC-123] @@ -190,16 +218,20 @@ Body explaining rationale, risks, test additions. Signed-off-by: Full Name ``` + Reject / rewrite any commit lacking sign-off. ### 6.10 Push & PR Creation + ```bash git push -u origin ABC-123 gh pr create --title "feat: support X [ABC-123]" --body "(temp)" ``` + Then PATCH the PR body with the HTML template (below). Use `gh pr edit` if needed. ### 6.11 PR Description (HTML Template) + ```html

Summary

Concise explanation of change.

@@ -216,15 +248,19 @@ Then PATCH the PR body with the HTML template (below). Use `gh pr edit` if neede ``` ### 6.12 Labels + Apply functional + aspect + Expeditor bump labels (if version semantics needed). See Label Reference. ### 6.13 Idempotency & Resume + If branch already exists: fetch + checkout. If PR exists: update in-place. Never duplicate PR. ### 6.14 Post-PR Iteration + On feedback: amend or follow-up commits (still DCO-signed). Keep commits logically grouped. ## 7. Branching & PR Standards + | Topic | Rule | |-------|------| | Branch Name | EXACT Jira ID or descriptive slug | @@ -234,29 +270,39 @@ On feedback: amend or follow-up commits (still DCO-signed). Keep commits logical | Labels | Add aspect + platform + Expeditor bump (if needed) | ## 8. Commit & DCO Policy + MANDATORY: Final line of every commit message: + ``` Signed-off-by: Full Name ``` + AI MUST refuse to generate unsigned commits. If contributor email unknown, request it first. No automation may strip the sign-off. ## 9. Testing & Coverage Enforcement + Commands: + ```bash bundle install bundle exec rake spec # runs rspec suite ``` + If coverage instrumentation added: + ```bash bundle exec rspec open coverage/index.html # manual review (macOS) ``` + Coverage Policy: + 1. Target >= 80% line & branch coverage. 2. If below threshold: list worst-offending files (lowest %), propose added examples. 3. Re-run until threshold passed. Edge Case Checklist (Authentication Logic): + - Expired timestamp (clock skew) - Incorrect digest algorithm specified - Missing required header(s) @@ -264,7 +310,9 @@ Edge Case Checklist (Authentication Logic): - Replay attempt (same nonce/timestamp if applicable) ## 10. Labels Reference + Core Mapping Guidance: + - bug/fix → Implementation defect - enhancement/feature → New capability - documentation → Docs-only change @@ -274,6 +322,7 @@ Core Mapping Guidance: - security → Security relevant change Repository Labels (Name → Description): + ``` Aspect: Documentation - How do we use this project? Aspect: Integration - Works correctly with other projects or systems. @@ -308,7 +357,9 @@ Platform: Unix-like - Generic Unix compatibility. ``` ## 11. CI / Expeditor Integration + ### GitHub Actions Workflows + 1. `lint.yml` - Triggers: `pull_request`, `push` to `main` - Purpose: Cookstyle/Rubocop style validation. @@ -318,7 +369,9 @@ Platform: Unix-like - Generic Unix compatibility. - Purpose: Unit test validation across environments. ### Expeditor (`.expeditor/config.yml`) + On PR merge into release branch: + 1. Version bump (unless skipped by label) 2. Update `VERSION` file & propagate to `lib/mixlib/authentication/version.rb` 3. Update CHANGELOG (unless skipped) @@ -326,11 +379,14 @@ On PR merge into release branch: Promoted pipeline triggers publish to RubyGems. ### Buildkite Pipeline (`verify.pipeline.yml`) + - Parallel steps for Ruby versions & platforms (Linux & Windows) using container executors. - Bundler caching to `vendor/bundle`. ## 12. Security & Protected Files + NEVER modify without explicit maintainer instruction: + - `LICENSE` - `CODE_OF_CONDUCT.md` - `.github/CODEOWNERS` @@ -340,13 +396,16 @@ NEVER modify without explicit maintainer instruction: - Any secret / credential / token references Disallowed actions: + - Writing plaintext secrets - Force-pushing to default branch (`master` or `main`) - Merging PRs - Adding large (>1MB) binary blobs ## 13. Prompts Pattern (Interaction Model) + Every major step output MUST include: + ``` Step Summary: Remaining Steps: @@ -355,10 +414,13 @@ Remaining Steps: Continue to next step? (yes/no) Recommended next prompt: "Proceed to with focus on ." ``` + No implicit progression: always wait for explicit `yes`. ## 14. Environment Preparation + Prerequisites: Ruby 3.1+ (or 3.4), Bundler, Git, GitHub CLI (`gh`). + ```bash git clone https://github.com/chef/mixlib-authentication.git cd mixlib-authentication @@ -366,15 +428,18 @@ bundle install bundle exec rake spec bundle exec rake style ``` + Optional (enable coverage): add SimpleCov (see Section 3) and re-run tests. ## 15. Idempotency & Recovery + - If branch exists locally: `git checkout ` - If remote only: `git fetch origin && git checkout ` - If PR exists: update via additional commits; do not recreate - If coverage instrumentation added previously: respect existing config; do not duplicate ## 16. Failure Handling + | Failure Type | Response | |--------------|----------| | Test failing | Identify spec/file; propose fix; re-run selectively | @@ -384,7 +449,9 @@ Optional (enable coverage): add SimpleCov (see Section 3) and re-run tests. | Jira fetch error | Ask for re-validation of ID or alternate task description | ## 17. Validation & Exit Criteria + Completion requires ALL: + 1. Plan approved by user. 2. Code changes implemented & tests added/updated. 3. Lint passes locally & in CI. @@ -396,12 +463,14 @@ Completion requires ALL: 9. User confirms closure: `Task complete? (yes/no)`. ## 18. Safeguards Summary + - Do not introduce secrets. - Do not disable tests or lower thresholds silently. - Do not remove license headers. - Always prompt before destructive or sweeping changes. ## 19. Quick Reference Commands + ```bash # Create branch git checkout -b ABC-123 @@ -423,6 +492,7 @@ gh pr create --title "feat: improve signature parsing [ABC-123]" --body "" ``` ## 20. Example Interaction Transcript (Pattern) + ``` User: Implement support for HMAC-SHA512 (Jira SEC-42) AI: Fetches SEC-42, outputs plan with impacted files, test matrix, asks: Continue? (yes/no) @@ -433,4 +503,53 @@ AI: PR created #123 with coverage 82.4%, labels applied. Continue to finalize? ( ``` --- + +## 21. AI-Assisted Development & Compliance + +- ✅ Create PR with `ai-assisted` label (if label doesn't exist, create it with description "Work completed with AI assistance following Progress AI policies" and color "9A4DFF") +- ✅ Include "This work was completed with AI assistance following Progress AI policies" in PR description + +### Jira Ticket Updates (MANDATORY) + +- ✅ **IMMEDIATELY after PR creation**: Update Jira ticket custom field `customfield_11170` ("Does this Work Include AI Assisted Code?") to "Yes" +- ✅ Use atlassian-mcp tools to update the Jira field programmatically +- ✅ **CRITICAL**: Use correct field format: `{"customfield_11170": {"value": "Yes"}}` +- ✅ Verify the field update was successful + +### Documentation Requirements + +- ✅ Reference AI assistance in commit messages where appropriate +- ✅ Document any AI-generated code patterns or approaches in PR description +- ✅ Maintain transparency about which parts were AI-assisted vs manual implementation + +### Workflow Integration + +This AI compliance checklist should be integrated into the main development workflow Step 4 (Pull Request Creation): + +``` +Step 4: Pull Request Creation & AI Compliance +- Step 4.1: Create branch and commit changes WITH SIGNED-OFF COMMITS +- Step 4.2: Push changes to remote +- Step 4.3: Create PR with ai-assisted label +- Step 4.4: IMMEDIATELY update Jira customfield_11170 to "Yes" +- Step 4.5: Verify both PR labels and Jira field are properly set +- Step 4.6: Provide complete summary including AI compliance confirmation +``` + +- **Never skip Jira field updates** - This is required for Progress AI governance +- **Always verify updates succeeded** - Check response from atlassian-mcp tools +- **Treat as atomic operation** - PR creation and Jira updates should happen together +- **Double-check before final summary** - Confirm all AI compliance items are completed + +### Audit Trail + +All AI-assisted work must be traceable through: + +1. GitHub PR labels (`ai-assisted`) +2. Jira custom field (`customfield_11170` = "Yes") +3. PR descriptions mentioning AI assistance +4. Commit messages where relevant + +--- + This document is living; propose additive improvements via PR (following all policies above). Avoid deletions or semantic weakening of guardrails.