fix(skills): harden credential provenance boundaries

[Bill Berry (WilliamBerryiii)]

fix(skills): harden credential provenance boundaries

Description

This change replaced shell evaluation of Jira credential files with bounded in-process loading and aligned the surrounding planner, backlog, Bash, evaluation, and security guidance. Credential files now supply inert configuration data, while write confirmation and debug controls remain inherited from the invoking process or explicit CLI flags.

Jira credential handling

• Added a standard-library dotenv parser with a supported-key allowlist and inherited-value precedence.
• Added descriptor protections for symlinks, non-regular files, oversized input, different POSIX owners, and group or other access.
• Limited record splitting to LF and CRLF so Unicode separators remain literal data.
• Rejected unconfirmed writes before reading ~/.jira.env, preventing the credential file from granting mutation authority.
• Added tests for parser edge cases, file metadata, secret-safe failures, and startup ordering.

Agent and guidance alignment

• Kept Functional Planner terminal use scoped to Jira search, get, comments, and fields operations.
• Routed missing Jira configuration to separate setup without shell sourcing or inline setup.
• Clarified repository-managed CI configuration provenance and kept non-CI authority classes outside that contract.
• Added and regenerated advisory behavior coverage for in-process loading, value-free stopping, and no credential disclosure.

Security and reference maintenance

• Expanded Jira skill and repository threat models for local credential-file ingestion and Windows ACL residual risk.
• Repaired stale external references that blocked repository link validation.
• Applied repository table and Python formatting to touched files.

Related Issue(s)

Fixes #2640
Fixes #2838

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Plan a Jira work-item hierarchy when Jira credentials may be stored in ~/.jira.env.

Execution Flow:

1. Functional Planner invokes only an allowed Jira read operation.
2. The Jira CLI loads supported missing values from ~/.jira.env as inert data.
3. The CLI rejects unsafe file metadata or incomplete configuration without printing values.
4. Credential setup remains separate, and writes require explicit CLI or inherited confirmation.

Output Artifacts:

The planner produces a read-only hierarchy plan and handoff. It does not create work items or modify credentials.

Success Indicators:

The CLI reports failures by variable name only, never shell-sources the file, and refuses unconfirmed writes before file access.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

• Jira tests: 210 passed, 1 platform-specific skip; Ruff passed
• Eval generator drift/schema/safety and 71 generator tests passed
• HVE static review and contained Medium-profile behavior simulation passed
• npm run validate:docs, npm run spell-check, npm run lint:md-links, and git diff --check passed
• Full npm run validate:local deferred to hosted CI per author direction

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local (deferred to hosted CI)
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

HVE behavior evidence is simulation-only and does not claim native Jira, filesystem, network, or tracker execution. Windows credential-file protection depends on operator-managed user-only ACLs. Hosted CI will run the full validation aggregate and normal PR status checks.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 92.20779% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.25%. Comparing base (48924be) to head (c3be875).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...ithub/skills/project-planning/jira/scripts/jira.py	92.20%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2842      +/-   ##
==========================================
+ Coverage   83.00%   84.25%   +1.25%     
==========================================
  Files         185       95      -90     
  Lines       34924    11414   -23510     
  Branches      228       27     -201     
==========================================
- Hits        28989     9617   -19372     
+ Misses       5861     1794    -4067     
+ Partials       74        3      -71     

Flag	Coverage Δ
docusaurus	90.60% <ø> (ø)
pester	83.41% <ø> (-0.01%)	⬇️
pytest	97.39% <92.20%> (+14.61%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ithub/skills/project-planning/jira/scripts/jira.py	97.39% <92.20%> (-0.75%)	⬇️

... and 91 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

✅ Status: Passed — no merge-blocking failures (24 advisory assertion failure(s) present)

• Artifacts evaluated: 3
• Specs run: 3
• Assertions passed: 11
• Assertions failed (blocking): 0
• Assertions failed (advisory): 24
• Failed specs (merge-blocking): 0

Artifact	Kind	Status	Specs	Passed	Failed (blocking)	Failed (advisory)
functional-planner	agent	⚠️ advisory-fail	1	0	0	20
backlog-management	skill	⚠️ advisory-fail	1	3	0	3
jira	skill	⚠️ advisory-fail	1	8	0	1

Legend — ✅ clean · ⚠️ advisory failures only (non-blocking) · ⏭️ skipped · ❌ merge-blocking failure

Only Failed specs (merge-blocking) gates this PR. Advisory assertion failures are signal-quality checks captured during iteration; review them, but they do not block merge and may be acceptable.