microsoft/hve-core

Commit

feat(skills): add experimental mural skill with Python CLI, instructions, and agent integrations (#1561)

# Pull Request

## Description

Adds the **experimental Mural skill** — a Python CLI for the Mural REST
API — together with the cross-cutting instruction set, agent
integrations, collection registrations, documentation, and supporting
validation guards needed to operate it.

The skill enables agents (DT Coach, RAI Planner, UX/UI Designer) to seed
and extract Mural workspaces, rooms, murals, and widgets while honoring
the *Mural-as-human-record* contract: AI never silently authors
decisions, all writebacks remain inspectable in Mural, and operator logs
never echo raw URLs, SAS query strings, OAuth tokens, or `Authorization`
headers.

Key changes by area:

* **Skill**: New `.github/skills/experimental/mural/` package with bash
and PowerShell entry scripts, a Python CLI (`scripts/mural.py`),
polyglot Atheris fuzz harness, full pyproject.toml with ruff/pytest
config, SECURITY.md, and `.env.example`.
* **Instructions**: Six new cross-cutting instruction files under
`.github/instructions/experimental/mural/` covering destinations
registry, human-record contract, log hygiene, seeding patterns,
writeback hygiene, and asymmetric writing style; plus an open
destination registry (`destinations/registry.yml`).
* **Agent integrations**: Mural seeding/writeback wiring added to
`dt-coach.agent.md`, `rai-planner.agent.md`, and
`ux-ui-designer.agent.md`.
* **Collections**: `hve-core-all` and `project-planning` collections
register the skill and all six instructions at `experimental` maturity;
entries alphabetized and tables reformatted via `format:tables`.
* **Docs**: New mural credentials guide
(`docs/security/mural-credentials.md`) wired into the Docusaurus
sidebar; security model (`docs/security/security-model.md`) extended
with sixteen Mural-skill threats (OA-1 .. OA-16) covering runtime,
OAuth, and writeback surfaces.
* **Scripts/validation**: `validate:skills` now requires the ruff
`isort` (`I`) rule when a Python skill ships a `tests/` directory, with
matching Pester tests.
* **Plugin output**: Regenerated `plugins/**` artifacts for both
affected collections (autogenerated; do not hand-edit).

## Related Issue(s)

Closes #1562

## Type of Change

**Code & Documentation:**

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

**Infrastructure & Configuration:**

* [ ] GitHub Actions workflow
* [x] Linting configuration (markdown, PowerShell, etc.)
* [x] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update

**AI Artifacts:**

* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [x] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [x] Copilot agent (`.github/agents/*.agent.md`)
* [x] Copilot skill (`.github/skills/*/SKILL.md`)

**Other:**

* [x] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

**User Request:**

> "Use the mural skill to seed our discovery mural with the affinity
clusters from the DT session,."

**Execution Flow:**

1. The DT Coach agent loads `.github/skills/experimental/mural/SKILL.md`
and the cross-cutting `mural-*.instructions.md` set.
2. Coach invokes the mural CLI (`scripts/mural.sh` / `mural.ps1`),
authenticating via OAuth credentials sourced from environment / keyring
per `mural-credentials.md`.
3. Outbound writeback follows `mural-seeding-patterns.instructions.md`
(duplicate-then-populate, anchor inheritance, probe-before-bulk) and
`mural-writing-style.instructions.md` (sticky-concise outbound).
4. Inbound extraction hydrates context per the asymmetric writing style
and respects reserved tags from
`mural-writeback-hygiene.instructions.md`.
5. All operator log lines pass through the skill's `_redact()` backstop;
agents additionally avoid echoing URLs, SAS query strings, or
`Authorization` headers per `mural-log-hygiene.instructions.md`.

**Output Artifacts:**

* New / updated Mural widgets (sticky notes, areas, tags, hyperlinks).
* Coaching-state file updates derived from extracted widget contents.
* Optional local JSON snapshots of murals/widgets when invoked through
the CLI.

**Success Indicators:**

* Mural reflects the seeded structure with reserved tags preserved and
no duplicated reserved-tag widgets.
* Operator logs contain no raw URLs, query strings, or token material.
* Coaching state captures inbound extracts with full context per the
inbound style contract.

## Testing

Automated validation performed during PR preparation (commands run from
repo root):

* `npm run lint:md` — pass
* `npm run lint:yaml` — pass
* `npm run lint:py` — pass
* `npm run lint:ps` — pass
* `npm run lint:frontmatter` — pass
* `npm run lint:md-links` — pass
* `npm run lint:marketplace` — pass
* `npm run lint:collections-metadata` — pass
* `npm run lint:ai-artifacts` — pass
* `npm run lint:version-consistency` — pass
* `npm run lint:permissions` — pass
* `npm run lint:dependency-pinning` — pass
* `npm run lint:links` — pass
* `npm run lint:models` — pass
* `npm run validate:skills` — pass
* `npm run validate:copyright` — pass
* `npm run plugin:generate` — clean (no diff after regen)
* `npm run test:ps` — 2178 passed, 0 failed, 3 skipped, 65 not-run
* `npm run test:py` — mural skill tests pass. Two failures in unrelated
skills are **pre-existing**:
* `tts-voiceover` — `tests/test_embed_audio.py` collection error:
`ModuleNotFoundError: No module named 'lxml'`
* `powerpoint` — `tests/test_generate_themes.py` collection error:
`ModuleNotFoundError: No module named 'ruamel'`

Diff-based assessments:

* No customer data, secrets, or NDA content in the diff.
* New CLI entry points (`mural.py`, `mural.sh`, `mural.ps1`) follow
least-privilege patterns and rely on env/keyring for credentials.
* New `validate:skills` guard (`isort 'I'` requirement) is additive;
existing skills already comply.

Manual testing not performed in this PR.

## Checklist

### Required Checks

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

### AI Artifact Contributions

* [ ] Used `/prompt-analyze` to review contribution
* [ ] Addressed all feedback from `prompt-builder` review
* [ ] Verified contribution follows common standards and type-specific
requirements

### Required Automated Checks

* [x] Markdown linting: `npm run lint:md`
* [ ] Spell checking: `npm run spell-check` (N/A — not run during PR
prep)
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`
* [x] Plugin freshness: `npm run plugin:generate`
* [ ] Docusaurus tests: `npm run docs:test` (N/A — not run during PR
prep)

## Security Considerations

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

Highlights:

* Sixteen new Mural-specific threats (OA-1 .. OA-16) are documented in
`docs/security/security-model.md` covering script-runtime, OAuth, and
writeback surfaces.
* `mural-log-hygiene.instructions.md` is the operator contract; the
skill's `_redact()` is a defense-in-depth backstop, not a license to log
secrets.
* New runtime deps for the skill (`shapely`, `scipy`, `networkx`,
`keyring`) are scoped to the skill's `pyproject.toml` and PEP 723 inline
metadata; no global dependency surface change.

## GHCP Artifact Maturity

> [!WARNING]
> This PR includes **experimental** GHCP artifacts that may have
breaking changes.
>
> * `.github/skills/experimental/mural/SKILL.md`
> *
`.github/instructions/experimental/mural/mural-destinations.instructions.md`
> *
`.github/instructions/experimental/mural/mural-human-record.instructions.md`
> *
`.github/instructions/experimental/mural/mural-log-hygiene.instructions.md`
> *
`.github/instructions/experimental/mural/mural-seeding-patterns.instructions.md`
> *
`.github/instructions/experimental/mural/mural-writeback-hygiene.instructions.md`
> *
`.github/instructions/experimental/mural/mural-writing-style.instructions.md`

| File | Type | Maturity | Notes |

|--------------------------------------------------------------|--------------|-----------------|---------------------------------------------|
| `experimental/mural/SKILL.md` | Skill | ⚠️ experimental | New skill in
`.github/skills/experimental/` |
| `experimental/mural/mural-destinations.instructions.md` | Instructions
| ⚠️ experimental | Open destination registry contract |
| `experimental/mural/mural-human-record.instructions.md` | Instructions
| ⚠️ experimental | Mural-as-human-record contract |
| `experimental/mural/mural-log-hygiene.instructions.md` | Instructions
| ⚠️ experimental | Operator log redaction contract |
| `experimental/mural/mural-seeding-patterns.instructions.md` |
Instructions | ⚠️ experimental | Cross-cutting seeding conventions |
| `experimental/mural/mural-writeback-hygiene.instructions.md` |
Instructions | ⚠️ experimental | Tag/parentId/hyperlink rules |
| `experimental/mural/mural-writing-style.instructions.md` |
Instructions | ⚠️ experimental | Asymmetric outbound/inbound style |

### GHCP Maturity Acknowledgment

* [ ] I acknowledge this PR includes non-stable GHCP artifacts
* [ ] Non-stable artifacts are intentional for this change

## Additional Notes

* `npm run test:py` reports two pre-existing failures (`tts-voiceover`
missing `lxml`, `powerpoint` missing `ruamel`) in skills not modified by
this PR. Tracking separately is recommended.
* Plugin output under `plugins/**` is autogenerated by `npm run
plugin:generate` (post-processed by `lint:md:fix` and `format:tables`);
do not hand-edit those files.

---------

Co-authored-by: Bill Berry <wbery@microsoft.com>
Co-authored-by: Marcel Bindseil <marcelbindseil@gmail.com>