fix(brief): tighten generated HTML guardrails

kime541200 · kime541200 · commit 24fbdd44e684 · 2026-06-25T11:31:04.000+08:00
Require brief output to keep full source artifact coverage, label inferred impacts, avoid fallback claims from non-goals, and stay standalone with system fonts and project-neutral branding.
diff --git a/docs/commands.md b/docs/commands.md
@@ -341,7 +341,9 @@ Generate a one-page HTML brief that helps you review a change before implementat
 
 **Important:**
 - The brief is not the source of truth; the original artifacts remain authoritative
+- The source artifact index includes every file path returned by the CLI context
 - Missing or ambiguous information is called out instead of invented
+- Generated HTML is standalone: no external fonts, CDN assets, network resources, unrelated branding, or agent-specific labels
 - Opening the file is best-effort; if it fails, the generated path is printed
 
 **Example:**
diff --git a/docs/opsx.md b/docs/opsx.md
@@ -209,6 +209,8 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 Reads the change artifacts and writes `brief.html` in the change directory. Use this optional workflow when you want a concise review surface before applying tasks. The original artifacts remain the source of truth.
 
+The generated brief is standalone local HTML. It should not depend on remote fonts, CDN assets, network resources, unrelated branding, or agent-specific labels, and it should show source attribution for substantive claims.
+
 ### Implement (the fluid part)
 ```
 /opsx:apply
diff --git a/openspec/changes/add-brief-workflow/design.md b/openspec/changes/add-brief-workflow/design.md
@@ -34,11 +34,18 @@ Alternative considered: add `openspec brief`. That would either be a weak determ
 
 The requested review surface is browser-readable HTML. A second `brief.md` output would create synchronization questions without being needed for the MVP.
 
+### Decision: Keep generated HTML self-contained and project-neutral
+
+The workflow should instruct agents to use inline CSS and system fonts only. It should not pull Google Fonts, CDN assets, remote images, or any other network resources into `brief.html`.
+
+The generated page should also avoid unrelated product names, project names, footers, and agent-specific implementation labels unless those details come from the source artifacts. This keeps the workflow portable across OpenSpec users and prevents local helper templates from leaking repo- or harness-specific branding into official output.
+
 ## Risks / Trade-offs
 
 - [Risk] Agent-generated summaries can be inaccurate. -> Mitigation: require source attribution, require missing information to be called out, and state that original artifacts remain authoritative.
 - [Risk] `open` behavior is platform-specific. -> Mitigation: document best-effort opener commands and treat opener failure as non-fatal.
 - [Risk] Adding a workflow id can affect profile drift detection and generated command cleanup. -> Mitigation: update workflow maps and targeted tests around profile, generation, and tool detection.
+- [Risk] Local or agent-specific brief templates can leak unrelated branding or external assets. -> Mitigation: require standalone, project-neutral HTML and explicitly forbid remote fonts, CDN links, network assets, unrelated footers, and harness-specific labels unless sourced from artifacts.
 
 ## Migration Plan
 
diff --git a/openspec/changes/add-brief-workflow/proposal.md b/openspec/changes/add-brief-workflow/proposal.md
@@ -8,7 +8,8 @@ The workflow needs an optional agent-generated review surface that summarizes th
 
 - Add an optional `/opsx:brief` workflow that produces a one-page HTML brief for an existing change.
 - The workflow reads the change status and apply context from the OpenSpec CLI, then reads the artifact files listed in `contextFiles`.
-- The agent synthesizes a concise human-readable brief with source attribution, risks, questions, implementation order, and verification plan.
+- The agent synthesizes a concise human-readable brief with source attribution, full source artifact coverage, risks, questions, implementation order, and verification plan.
+- The generated HTML is standalone and generic to the OpenSpec change: no external fonts, CDN links, network assets, unrelated branding, or agent-specific implementation labels.
 - The workflow writes `brief.html` inside the change directory and best-effort opens it with the host OS.
 - The workflow is selectable through the custom profile but is not included in the default `core` profile.
 
diff --git a/openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md b/openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md
@@ -31,6 +31,15 @@ The brief workflow SHALL synthesize content from existing OpenSpec artifacts wit
 - **WHEN** the brief states a claim derived from an artifact
 - **THEN** the brief SHALL include source attribution to the relevant artifact path or artifact id
 
+#### Scenario: Source artifact coverage
+- **WHEN** generating the source artifact index
+- **THEN** the brief SHALL include every file path returned in `contextFiles`
+- **AND** SHALL NOT silently omit delta spec files or schema-specific artifacts
+
+#### Scenario: Inferred impacts
+- **WHEN** the brief includes affected modules, file areas, behavior changes, risks, or questions not explicitly stated by artifacts
+- **THEN** the brief SHALL label them as inference
+
 ### Requirement: HTML Brief Content
 The generated brief SHALL be concise, readable, and review-oriented.
 
@@ -50,7 +59,13 @@ The generated brief SHALL be concise, readable, and review-oriented.
 #### Scenario: Static local HTML
 - **WHEN** writing `brief.html`
 - **THEN** the file SHALL be standalone static HTML
-- **AND** SHALL NOT depend on external JavaScript, CSS, fonts, or network resources
+- **AND** SHALL NOT depend on external JavaScript, CSS, fonts, CDN links, images, or network resources
+- **AND** SHALL use system fonts instead of remote fonts
+
+#### Scenario: Generic OpenSpec output
+- **WHEN** writing `brief.html`
+- **THEN** the file SHALL NOT include unrelated product names, project names, footers, or branding unless present in the source artifacts
+- **AND** SHALL NOT include agent- or harness-specific paths or labels unless present in the source artifacts
 
 ### Requirement: Optional Workflow Installation
 The brief workflow SHALL be available for custom profile selection but not installed by the default core profile.
diff --git a/openspec/changes/add-brief-workflow/tasks.md b/openspec/changes/add-brief-workflow/tasks.md
@@ -5,6 +5,7 @@
 - [x] 1.3 Instruct agents to read `status --json`, `instructions apply --json`, and all `contextFiles`
 - [x] 1.4 Require a static local `brief.html` output with source attribution and no external assets
 - [x] 1.5 Include best-effort OS opener behavior with graceful fallback
+- [x] 1.6 Add fidelity guardrails for source artifact coverage, inferred impacts, task grouping, and project-neutral HTML output
 
 ## 2. Generation Integration
 
diff --git a/src/core/templates/workflows/brief-change.ts b/src/core/templates/workflows/brief-change.ts
@@ -59,6 +59,12 @@ ${STORE_SELECTION_GUIDANCE}
 
    Create a concise, human-readable review surface. The brief should help a user understand the change in about 3 minutes without reading every artifact.
 
+   Before writing HTML, build a short internal outline from the artifacts:
+   - Source artifact index: every file path returned in \`contextFiles\`, grouped by artifact ID
+   - Delta spec coverage: every spec file from \`contextFiles.specs\`
+   - Task coverage: task groups aligned with the numbered headings in the tasks artifact; if tasks are summarized, say so
+   - Impact list: affected modules or file areas stated by the artifacts; mark inferred impacts as "Inference"
+
    Include these sections:
    - What this change does
    - Explicit non-goals
@@ -73,8 +79,11 @@ ${STORE_SELECTION_GUIDANCE}
    **Accuracy rules**
    - The original OpenSpec artifacts remain the source of truth. The brief is only a review surface.
    - Every substantive claim must include source attribution such as \`Source: proposal.md\`, \`Source: design.md\`, \`Source: specs/<capability>/spec.md\`, or \`Source: tasks.md\`.
+   - The source artifact index must include every file path returned in \`contextFiles\`; do not silently drop delta specs or schema-specific artifacts.
    - If a section is not specified by the source artifacts, write "Not specified in source artifacts" instead of inventing content.
    - Separate direct source facts from your inference. Label inference as "Inference".
+   - Do not turn non-goals into fallback plans or implied future work unless the source artifacts explicitly say so.
+   - Do not add affected files, modules, user-visible behavior, risks, or questions unless they are sourced or clearly labeled as inference.
    - Keep the page concise. Prefer short bullets and compact tables over long prose.
 
 6. **Write static HTML**
@@ -86,8 +95,11 @@ ${STORE_SELECTION_GUIDANCE}
 
    The HTML must be:
    - standalone static HTML
-   - no external JavaScript, CSS, fonts, images, or network resources
+   - no external JavaScript, CSS, fonts, images, CDN links, or network resources
+   - use system fonts only; do not import Google Fonts or other remote fonts
    - professional and readable in a browser
+   - generic to the current OpenSpec change; do not include unrelated product names, project names, footers, or branding unless they appear in the source artifacts
+   - agent-agnostic; do not hardcode tool-specific paths or labels such as \`.codex\`, \`.agents\`, Claude, Codex, or any harness-specific implementation detail unless the source artifacts explicitly mention them
    - safe for artifact text: escape \`&\`, \`<\`, \`>\`, \`"\`, and \`'\` if you include source excerpts or user-provided content
 
    Use inline \`<style>\` only. Do not create additional files.
diff --git a/test/core/shared/skill-generation.test.ts b/test/core/shared/skill-generation.test.ts
@@ -57,6 +57,17 @@ describe('skill-generation', () => {
       expect(uniqueIds.size).toBe(templates.length);
     });
 
+    it('should keep brief output standalone and project-neutral', () => {
+      const brief = getSkillTemplates().find(t => t.workflowId === 'brief');
+
+      expect(brief?.template.instructions).toContain('contextFiles');
+      expect(brief?.template.instructions).toContain('Source artifact index');
+      expect(brief?.template.instructions).toContain('no external JavaScript, CSS, fonts, images, CDN links, or network resources');
+      expect(brief?.template.instructions).toContain('use system fonts only');
+      expect(brief?.template.instructions).toContain('do not include unrelated product names, project names, footers, or branding');
+      expect(brief?.template.instructions).toContain('mark inferred impacts as "Inference"');
+    });
+
     it('should filter by workflow IDs when provided', () => {
       const filtered = getSkillTemplates(['propose', 'explore', 'apply', 'archive']);
       expect(filtered).toHaveLength(4);
diff --git a/test/core/templates/skill-templates-parity.test.ts b/test/core/templates/skill-templates-parity.test.ts
@@ -41,15 +41,15 @@ const EXPECTED_FUNCTION_HASHES: Record<string, string> = {
   getNewChangeSkillTemplate: '39663a6d2037e6697020393a66f6327506e3e3bc573b7a3556dcb7f9457dc51d',
   getContinueChangeSkillTemplate: '1bb28875d6e5946ea2ec5f12e90f55d9784c2fa1f6e4c4e2d0eda53d861d4c75',
   getApplyChangeSkillTemplate: '0f5a15fc7fb9ad6059a5643d0e01365d27642637a4aaebf182f9eabb45348197',
-  getBriefChangeSkillTemplate: '02128880c929ff6d946a71ec41505a17c00bf251437133aaff4fdf0591644410',
+  getBriefChangeSkillTemplate: 'ff06252ffdf94a86a4c9b2cd0c03a3374207b3ba929f42c1bec420e16bddaf03',
   getFfChangeSkillTemplate: '9f4c12a1c58c723c9c45a139307eb90caf39cedd93c435bc960d0817328875e2',
   getSyncSpecsSkillTemplate: '75abb20572256e2b8a647e77befae99f109ab5c4dc954a9c3c184829b5fcaa40',
   getOnboardSkillTemplate: 'e871d8ce172bb805ae62a7611aee7a3154d89414f427ad5ef31721c903f13002',
   getOpsxExploreCommandTemplate: '37e53590aae7ac6621d4393aa80a5b8af21881323887fa924ed329199fda27e0',
   getOpsxNewCommandTemplate: '57c600cce318d16b9b4308a18d0d983ea3c0673034e606a7cceec07b4c705e87',
   getOpsxContinueCommandTemplate: '418108b417107a87019d4020b26c105792d2ef0110fe6920445e255889216716',
   getOpsxApplyCommandTemplate: 'daeb507206707169de73c828e199648dde5732cbc17791ef2a027adffd028574',
-  getOpsxBriefCommandTemplate: '51ba22fd5dc87650df50395cc655d69344b249f1b22dfb00f7aaca49b31b9563',
+  getOpsxBriefCommandTemplate: 'c2884976627c6e9deabcf227b387671e1891d4b0ee66e50dd90b3a47a35fc3e3',
   getOpsxFfCommandTemplate: '36973ae0dd00ab169fbaaa42bf565f97e1bc97cf63ae7c07307734cc1ca8c1fd',
   getArchiveChangeSkillTemplate: 'c511a1c943bcfc5f9f3833b8c0ff284b22d34864a08f5f553cec471ee485d38f',
   getBulkArchiveChangeSkillTemplate: '0f635913757ae3d1609e111f4a8f699443ca47cbaaf8a1b21eb652f7b96a1d13',
@@ -69,7 +69,7 @@ const EXPECTED_GENERATED_SKILL_CONTENT_HASHES: Record<string, string> = {
   'openspec-new-change': 'bdb534d6d5a00b235f63852af089f904fd20df34be526ef67990ec3183829f33',
   'openspec-continue-change': '5d2aea621310d74d89e547d705d2e08e6d5a44da7bca93ba049ed43ebf60295e',
   'openspec-apply-change': '54cffa61274c6a499d2b3775e9f6db29255fd8e5ad99d7352c1e3bbe2edb45ed',
-  'openspec-brief-change': 'f49222a1b4ff50eb53307b0f6cea511559066732d6f6f30e7a2698e6b2591731',
+  'openspec-brief-change': 'a6268b84bd87f59e40e772e67043a1eca589b6d7e387f05bc74a99505ffebf1a',
   'openspec-ff-change': 'cbb7844c130bd188319ff2b3f0c0320243b5ae5b588a0f816cd4e29408f25676',
   'openspec-sync-specs': 'a81fd87f5e871874eab72e57c10a1949fde46d1d07d95f8ea3bc1a52b4e78c43',
   'openspec-archive-change': '833290ade47ddaed7f5e523d07437c7cef2497340021e944096bce449e290c22',
