Skip to content

Commit ceb8c47

Browse files
fix(skills): tighten strict-tier cite-only licensing in ADR standards (#1859)
# Pull Request ## Description This PR tightened the strict-tier cite-only licensing posture of the ADR standards so that the project's published architecture-decision guidance no longer reproduces third-party copyrighted text. It resolved three strict-tier audit findings on the main branch. The IEEE 42010 reference in the *adr-author* standards excerpts was reduced to a strict cite-only form. The bullet now carries the precise designator *ISO/IEC/IEEE 42010:2022*, the official standard title, the ISO catalog URL, and an explicit "cite only; do not quote" qualifier, replacing the weaker prior phrasing. The Y-Statement formula in *adr-standards.instructions.md* previously reproduced the published six-slot sentence verbatim. It was replaced with an original HVE rendering of the same six-slot structure, and the attribution blockquote was corrected to credit Olaf Zimmermann and Uwe Zdun for the concept while clarifying that the template wording is HVE's own and not a reproduction of the published sentence. The matching Y-Statement slot description in the *adr-author* standards excerpts was reworded into the project's own phrasing so the skill reference stays aligned with the instructions and retains the Zimmermann and Zdun citation without echoing the source text. ## Related Issue(s) Closes #1858 ## Type of Change **Code & Documentation:** * [x] Documentation update **AI Artifacts:** * [x] Copilot instructions (`.github/instructions/*.instructions.md`) * [x] Copilot skill (`.github/skills/*/SKILL.md`) ## Testing Ran the relevant validation suite against the edited files: frontmatter validation (560 files, 0 errors), skill structure validation (21 skills, 0 errors), collection metadata validation (13 collections, 0 errors), and plugin validation (13 collections, 0 errors). The edited files produced no markdown lint output; the only `lint:md` failures are pre-existing and unrelated, in `evals/results/subagent-stimuli/`. ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) ### Required Automated Checks * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` ## Security Considerations * [x] This PR does not contain any sensitive or NDA information ## Additional Notes The plugin and extension copies of these instruction and skill files are relative symlinks to the sources, so the edits propagate automatically and require no regenerated output. Follow-on items identified during the audit but out of scope here include reconciling the audit M-6 wording, the separate BRD strict-tier remediation thread, and normalizing the Nygard cite-only separator.
1 parent 2ad24fd commit ceb8c47

5 files changed

Lines changed: 24 additions & 23 deletions

File tree

.github/instructions/project-planning/adr-identity.instructions.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Every conversation turn that elicits decision content runs through three interna
2626
* Do not select the chosen option for the user.
2727
* Do not skip a phase or partially advance one. Hard gates remain hard.
2828
* Do not prescribe a target system, decider list, or supersession link.
29+
* Do not solicit or record personal contact information, secrets, credentials, or third-party PII; steer stakeholder capture toward roles or team handles.
2930
* Do not lecture on MADR or ASR theory. Reference standards only when the user asks or a hard gate requires it.
3031

3132
## Progressive Hint Engine

.github/instructions/project-planning/adr-standards.instructions.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,11 +98,11 @@ Chosen option: "{title of option 1}", because {justification. e.g., only option,
9898

9999
The Y-Statement is a six-slot decision capture formula authored by Olaf Zimmermann and Uwe Zdun. The formula condenses an architectural decision into a single sentence covering use case, concern, chosen option, alternatives, target quality, and accepted downside.
100100

101-
> Attribution: Olaf Zimmermann and Uwe Zdun. The six-slot formula is reproduced verbatim below from the published Y-Statement formulation.
101+
> Attribution: The Y-Statement concept originates with Olaf Zimmermann and Uwe Zdun. The six-slot template below is an original HVE rendering of that structure, not a reproduction of the published sentence.
102102
103103
The six slots, in order, are:
104104

105-
> In the context of (USE CASE), facing (CONCERN), we decided for (OPTION) and against (ALTERNATIVES), to achieve (QUALITY), accepting (DOWNSIDE).
105+
> For (USE CASE), given (CONCERN), choose (OPTION) rather than (ALTERNATIVES) to gain (QUALITY) while accepting (DOWNSIDE).
106106
107107
Slot definitions:
108108

@@ -210,7 +210,7 @@ Paraphrased guidance:
210210
* Capture the architectural decision close to the time it is made, while context, drivers, and considered alternatives are still fresh; latency reduces fidelity.
211211
* Record the decision as an immutable artifact in the same repository as the system it governs so that history travels with the code.
212212
* Treat each ADR as version-controlled; do not edit accepted decisions to change their meaning. When circumstances change, supersede the prior decision with a new ADR that links back to the original.
213-
* Identify the decision-makers, consulted parties, and informed stakeholders explicitly so that accountability is unambiguous.
213+
* Identify the decision-makers, consulted parties, and informed stakeholders by role or name so that accountability is unambiguous.
214214
* Capture both the chosen option and the alternatives considered, with the reasoning that led to selection. Future maintainers benefit as much from understanding the discarded options as from the chosen one.
215215
* Surface tradeoffs, including the qualities sacrificed and the constraints accepted. Hidden tradeoffs become future surprises.
216216
* Keep the language plain and the scope tight; one decision per record makes downstream linkage and supersession tractable.

.github/skills/project-planning/adr-author/SKILL.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The state machine, hard exit gates, autonomy tiers (`manual`, `partial`, `full`)
3737
Activities:
3838

3939
- **Scope** — capture the decision in one or two sentences; bound it to a single project.
40-
- **Decision-makers** — record `deciders`, `consulted`, `informed` (RACI-aligned).
40+
- **Decision-makers** — record `deciders`, `consulted`, `informed` (RACI-aligned). Prefer a role or team handle over a personal name, and never record personal contact details, secrets, credentials, or third-party or customer PII in any ADR field.
4141
- **Drivers** — list decision drivers (functional needs, business goals).
4242
- **Constraints** — list non-negotiables (regulatory, platform, contractual, time).
4343
- **ASR trigger evaluation** — required when `state.outputTemplate == 'madr-v4'`. Evaluate triggers against the rubric in `adr-standards.instructions.md` and record results in `state.asrTriggers[]`. Defer the rubric and full taxonomy to that file and to `references/asr-trigger-taxonomy.md`.

.github/skills/project-planning/adr-author/references/standards-excerpts.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Markdown Any Decision Records (MADR) is a lean ADR template optimized for collab
2626

2727
## Y-Statement
2828

29-
The Y-Statement is a six-slot single-sentence decision capture formula authored by Olaf Zimmermann and Uwe Zdun. It condenses an architectural decision into: use case, concern, chosen option, rejected alternatives, target quality, and accepted downside. The `adr-author` skill uses the Y-Statement as the primary output of `capture` entry mode for low-stakes or reversible decisions where a full MADR long-form would be over-investment.
29+
The Y-Statement is a six-slot single-sentence decision capture formula authored by Olaf Zimmermann and Uwe Zdun. It captures an architectural decision across six ordered slots, rendered in HVE's own wording: the use case, the concern in tension, the chosen option, the rejected alternatives, the target quality, and the accepted downside. The `adr-author` skill uses the Y-Statement as the primary output of `capture` entry mode for low-stakes or reversible decisions where a full MADR long-form would be over-investment.
3030

3131
- Citation: Olaf Zimmermann and Uwe Zdun, "Y-Statements: A Light Template for Architectural Decision Capturing", published via the Architectural Decision Records community materials (ozimmer.ch / SATURN tutorials, 2018-onward).
3232
- Purpose in `capture` mode: produce a single durable sentence that records the decision and its tradeoff without demanding an options analysis.
@@ -52,7 +52,7 @@ The Microsoft code-with-engineering-playbook documents the team practice of main
5252
The following sources inform the practice but MUST NOT be embedded verbatim in skill outputs or templates. Reference them by citation only.
5353

5454
- Michael Nygard, "Documenting Architecture Decisions" (2011) — the foundational ADR essay that established the Context / Decision / Status / Consequences shape later refined by MADR.
55-
- IEEE 42010:2022"Software, systems and enterprise — Architecture description". Standardizes architecture description elements including architecture decisions and their rationale.
55+
- ISO/IEC/IEEE 42010:2022, "Software, systems and enterprise — Architecture description". ISO catalog: <https://www.iso.org/standard/74393.html>. Cite only; do not quote.
5656
- arc42 §9 — "Architecture Decisions" section of the arc42 documentation template, providing a lightweight rationale-capture pattern complementary to MADR.
5757
- joelparkerhenderson/architecture-decision-record — community catalog of ADR templates and examples. Licensed under CC-BY-SA; embedding text would impose share-alike obligations on hve-core and is therefore prohibited. Cite by URL only.
5858

scripts/agents/activation-harness/baseline.json

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,27 @@
22
"CleanWorkspace": {
33
"ScenarioName": "CleanWorkspace",
44
"AgentBytes": 10096,
5-
"ColdStartBytes": 39456,
5+
"ColdStartBytes": 39611,
66
"LoadedFiles": [
77
{
88
"Path": ".github/agents/project-planning/adr-creation.agent.md",
99
"Bytes": 10096
1010
},
1111
{
1212
"Path": ".github/instructions/project-planning/adr-identity.instructions.md",
13-
"Bytes": 24132
13+
"Bytes": 24287
1414
},
1515
{
1616
"Path": ".github/instructions/shared/disclaimer-language.instructions.md",
1717
"Bytes": 5228
1818
}
1919
],
20-
"Hash": "040ed800dd6635ef75de95bb8a201441d8c59194f8b9a547ba64719ee836376a"
20+
"Hash": "e7134dfc8e7534b972af260c5e403a31d9824e6db3df74620af82a7da3fec47e"
2121
},
2222
"SteadyState": {
2323
"ScenarioName": "SteadyState",
2424
"AgentBytes": 10096,
25-
"ColdStartBytes": 79798,
25+
"ColdStartBytes": 80004,
2626
"LoadedFiles": [
2727
{
2828
"Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -38,23 +38,23 @@
3838
},
3939
{
4040
"Path": ".github/instructions/project-planning/adr-identity.instructions.md",
41-
"Bytes": 24132
41+
"Bytes": 24287
4242
},
4343
{
4444
"Path": ".github/instructions/project-planning/adr-standards.instructions.md",
45-
"Bytes": 16098
45+
"Bytes": 16149
4646
},
4747
{
4848
"Path": ".github/instructions/shared/disclaimer-language.instructions.md",
4949
"Bytes": 5228
5050
}
5151
],
52-
"Hash": "296bb1a41437c68ea6e656b0c84cc6a6cd452054a0776d37004a8a2029df4e9e"
52+
"Hash": "599486f52d9dd47eb10fe3f13e5d98352d46d95af6666b750a01504e2d1d85ee"
5353
},
5454
"GovernEntry": {
5555
"ScenarioName": "GovernEntry",
5656
"AgentBytes": 10096,
57-
"ColdStartBytes": 93164,
57+
"ColdStartBytes": 93535,
5858
"LoadedFiles": [
5959
{
6060
"Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -70,27 +70,27 @@
7070
},
7171
{
7272
"Path": ".github/instructions/project-planning/adr-identity.instructions.md",
73-
"Bytes": 24132
73+
"Bytes": 24287
7474
},
7575
{
7676
"Path": ".github/instructions/project-planning/adr-standards.instructions.md",
77-
"Bytes": 16098
77+
"Bytes": 16149
7878
},
7979
{
8080
"Path": ".github/instructions/shared/disclaimer-language.instructions.md",
8181
"Bytes": 5228
8282
},
8383
{
8484
"Path": ".github/skills/project-planning/adr-author/SKILL.md",
85-
"Bytes": 13366
85+
"Bytes": 13531
8686
}
8787
],
88-
"Hash": "2f5812441a5943baa0723f9689c6aa3726253a743256ff6f1ad5fe9f4cf273c1"
88+
"Hash": "8c30014845d6df6853f69fe7cb210f495910bccc9464b62af3606d51c1ddb568"
8989
},
9090
"AdoptTemplate": {
9191
"ScenarioName": "AdoptTemplate",
9292
"AgentBytes": 10096,
93-
"ColdStartBytes": 100158,
93+
"ColdStartBytes": 100529,
9494
"LoadedFiles": [
9595
{
9696
"Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -106,11 +106,11 @@
106106
},
107107
{
108108
"Path": ".github/instructions/project-planning/adr-identity.instructions.md",
109-
"Bytes": 24132
109+
"Bytes": 24287
110110
},
111111
{
112112
"Path": ".github/instructions/project-planning/adr-standards.instructions.md",
113-
"Bytes": 16098
113+
"Bytes": 16149
114114
},
115115
{
116116
"Path": ".github/instructions/shared/disclaimer-language.instructions.md",
@@ -122,9 +122,9 @@
122122
},
123123
{
124124
"Path": ".github/skills/project-planning/adr-author/SKILL.md",
125-
"Bytes": 13366
125+
"Bytes": 13531
126126
}
127127
],
128-
"Hash": "58482298f587bc5d78344c126179dcc424f40b65bde92160a152062317420979"
128+
"Hash": "fbf486cab4fb03fa741a0d75e7aea1d3a878d68e906137cabdba83c32ff2d6bb"
129129
}
130130
}

0 commit comments

Comments
 (0)