Fix governance-cli and repo-hygiene CI failures: add package.json and fix broken link

[Copilot]

Two CI checks on this PR were failing: governance-cli-check due to missing package.json, and repo-hygiene due to a broken markdown link pointing to a build-time artifact.

Remediation PR -- Metadata

Target file: index.qmd, package.json, package-lock.json
Issue: CI failures on jobs 70984663025 (governance-cli) and 70984663005 (repo-hygiene)
Type: missing-npm-manifest, broken-internal-link

Summary

• Change: Add package.json + package-lock.json so npm ci succeeds in CI; fix index.qmd markdown link to resolve against source tree instead of build output
• UIAO ID: N/A
• Owner: N/A
• Status: N/A

Changes

• Add package.json at repo root:
  • "type": "module" — matches ES module imports in tools/uiao-governance-cli.js
  • "dependencies": { "js-yaml": "^4.1.0" } — the only external import in the CLI
• Add package-lock.json (generated via npm install) — enables reproducible npm ci in CI
• Fix index.qmd line 11:

  - Redirecting to [UIAO Modernization Atlas](docs/index.html)...
  + Redirecting to [UIAO Modernization Atlas](docs/index.qmd)...

  docs/index.html is generated at build time and not present in the source tree; check_links.py validates against source files via Path.exists().

Rationale

governance-cli-check.yml runs npm ci || npm install with no fallback beyond that — without a package.json both commands fail with ENOENT. The js-yaml dependency is a hard import at the top of tools/uiao-governance-cli.js and will crash at runtime without it.

repo-hygiene runs scripts/check_links.py, which resolves markdown links relative to the source file using filepath.parent / base and calls .exists(). Generated .html files are in .gitignore and never present in the checkout, so the link must target the .qmd source.

Branch naming

copilot/fix-package-json-and-broken-link

Commit message format

fix(ci): add package.json with js-yaml dep and fix broken link in index.qmd

Checklist

• Used canonical UIAO frontmatter template
• uiao.id follows UIAO_<AppendixLetter>_<Number>
• uiao.status is one of: Current, Draft, Needs Replacing, Needs Creating, Deprecated
• uiao.owner is a team or role
• uiao.tags present and relevant
• Status badge present in top 8 lines
• Diagrams include title and desc if applicable
• Local validation passed: node scripts/validate_uiao_metadata.js
• CI validation passes

Reviewer guidance

• Confirm package.json "type": "module" matches the CLI's import syntax
• Confirm js-yaml is the only missing dependency (no other import statements require external packages)
• Confirm docs/index.qmd exists in source tree (it does — verified locally)
• Note: the <meta http-equiv="refresh"> tag in index.qmd intentionally retains url=docs/index.html — that is the correct deployed URL; only the markdown link (checked by check_links.py) was changed

Post-merge actions

• Verify both governance-cli-check and repo-hygiene CI jobs pass on next run
• Confirm package-lock.json is not excluded by .gitignore (it is not — node_modules/ is ignored, lockfile is not)

Original prompt

Pull request #15 has two failing CI checks that need to be fixed:

Issue 1: Missing package.json (Job 70984663025 - governance-cli)

The workflow governance-cli-check.yml tries to run npm ci || npm install but fails because neither package.json nor package-lock.json exist in the repository. The fallback to npm install also fails with "ENOENT: no such file or directory, open package.json".

Issue 2: Broken Link (Job 70984663005 - repo-hygiene)

The file /index.qmd line 11 contains a broken link: [UIAO Modernization Atlas](docs/index.html). The link checker cannot resolve docs/index.html because it's a generated file that only exists at build time. The actual source file is docs/index.qmd.

Solution

1. Create package.json at the repository root with minimal configuration for npm to recognize the project
2. Create package-lock.json to lock dependency versions
3. Update the link in index.qmd from docs/index.html to docs/index.qmd so the link checker can validate it against the actual source files

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Please find a solution for failing job 70984663005. Use the logs, job definition, and any referenced files where the failure occurred. Keep your response focused on the solution and include code suggestions when appropriate.

Assistant: I'll help you find a solution for the failing job. Let me start by retrieving the logs for that job.

Assistant: The job failed because of a broken internal link. Let me get the file with the broken link to understand the issue better.

Assistant: ## Solution for Job 70984663005

Problem: The link checker found a broken internal link in index.qmd pointing to docs/index.html, but the file structure doesn't match this reference.

Root Cause: The index.qmd file at the repository root (line 11) references docs/index.html as a redirect target, but based on the file structure, the actual content is in docs/index.qmd or site/index.qmd. The link checker expects the target to exist as a valid file reference.

Solution: Update the broken link in /index.qmd to point to the correct location:

---
title: "UIAO Modernization Atlas"
format:
  html:
    page-layout: custom
    include-in-header:
      - text: |
          <meta http-equiv="refresh" content="0; url=docs/index.html" />
---

Redirecting to [UIAO Modernization Atlas](../docs/index.html)...

Alternative approach (if docs/index.html doesn't render as expected): If the build process doesn't generate docs/index.html from docs/index.qmd, update the redirect to use the source file:

Redirecting to [UIAO Modernization Atlas](docs/index.qmd)...

Or ensure the meta refresh tag matches the link text:

<meta http-equiv="refresh" content="0; url=docs/" />

The link checker will pass once the markdown link target resolves to an actual file in the repository structure.

User: fix please

Assistant: Now I'll create a pull request to fix the broken link:

Assistant: I'm waiting for your approval to proceed with creating a pull request to fix the broken link. The tool will update index.qmd line 11 to change docs/index.html to docs/index.qmd so the link checker can validate the target file exists in the repository.

User: @copilot Accepted Confirmation: Confirm agent session

Assistant: I've initiated the fix for the broken link in index.qmd. Here's your task tracking link:

data:
    - title: '[WIP] Fix broken link in index.qmd for link checker'
      repository: WhalerMike/uiao-docs
      url: https://github.com/copilot/tasks/pull/PR_kwDORrsKbc7RzM_6?session_id=a1f71efe-5454-4e69-b9ae-0f072da626f7
      state: queued

What's being fixed:

• File: index.qmd line 11
• Change: docs/index.html → docs/index.qmd
• Reason: The link checker validates against source files in the repository. It cannot resolve .html files that are only generated at build time. By linking to the actual source file, the link checker will pass validation.

The pull request will update the redirect link to reference the actual source file that exists in the repository structure.

User: Please find a solution for failing job 70984663025. Use the logs, job definition, and any referenced files where the failure occurred. Keep your response focused on the solution and include code suggestions when appropriate.

Assistant: Now let me check the workflow file and the repository structure:

Assistant: ## Solution for Job 70984663025

Problem: The workflow governance-cli-check.yml fails at the dependency installation step because package.json doesn't exist in the repository.

Root Cause: The workflow attempts to run npm ci || npm install (line 21), but the repository lacks a package.json file. When npm ci fails (no lockfile), it falls back to npm install, which also fails because it can'...

This pull request was created from Copilot chat.