[codex] fix metadata sync fallback and docs alignment #1014
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -81,13 +81,14 @@ Template labels must remain canonical and pass: | |||||||||||||||||||||||
| - `Priority` | ||||||||||||||||||||||||
| - `Type` | ||||||||||||||||||||||||
| - `Effort` | ||||||||||||||||||||||||
| - `Start date` and `Target date` when `status:ready` or `status:in-progress` is present | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Derivation source notes: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| - `Status`, `Priority`, and `Type` are mapped from labels via `.github/issue-fields.yml` mappings. | ||||||||||||||||||||||||
| - `Effort` uses the configured default from canonical issue-fields configuration. | ||||||||||||||||||||||||
| - `Type` and `Priority` now fall back to safe content-based inference when labels are missing or late. | ||||||||||||||||||||||||
| - `Start date` and `Target date` are populated when kickoff-ready metadata is present (`status:ready` or `status:in-progress`) and the workflow reprocesses label changes so fields can catch up after triage. | ||||||||||||||||||||||||
| - Metadata governance for assignees, milestones, and relationships is handled separately by `.github/workflows/metadata-governance.yml`. | ||||||||||||||||||||||||
|
Comment on lines
88
to
92
Contributor
There was a problem hiding this comment. Add missing comma in compound sentence (line ~91). The clause "the workflow reprocesses label changes so fields can catch up after triage" needs a comma before "so" to properly join two independent clauses. It should read: "…label changes, so fields can catch up…" 🔧 Proposed fix-- `Type` and `Priority` now fall back to safe content-based inference when labels are missing or late.
-- `Start date` and `Target date` are populated when kickoff-ready metadata is present (`status:ready` or `status:in-progress`) and the workflow reprocesses label changes so fields can catch up after triage.
+- `Type` and `Priority` now fall back to safe content-based inference when labels are missing or late.
+- `Start date` and `Target date` are populated when kickoff-ready metadata is present (`status:ready` or `status:in-progress`), and the workflow reprocesses label changes, so fields can catch up after triage.📝 Committable suggestion
Suggested change
🧰 Tools🪛 LanguageTool[uncategorized] ~88-~88: Loose punctuation mark. (UNLIKELY_OPENING_PUNCTUATION) [uncategorized] ~88-~88: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~91-~91: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE_2) [uncategorized] ~92-~92: The official name of this software platform is spelled with a capital “H”. (GITHUB) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Current preflight conditions must be satisfied before sync runs: | ||||||||||||||||||||||||
|
|
@@ -98,7 +99,7 @@ Current preflight conditions must be satisfied before sync runs: | |||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Safe automation boundary: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| - Active write path covers the five core derived fields plus kickoff-aware date handling. | ||||||||||||||||||||||||
| - Additional direct issue-field writes are out of scope until a dedicated follow-up verification approves extension. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Verification reference: `.github/reports/audits/2026-06-07-private-project-issue-field-write-verification-879.md`. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,9 +2,9 @@ | |
| title: GitHub Issue Creation Guide | ||
| description: How to create well-formed issues, select templates, and trigger automation | ||
| file_type: documentation | ||
| version: "1.0.6" | ||
| created_date: "2026-05-31" | ||
| last_updated: "2026-06-19" | ||
| author: Claude Code | ||
| maintainer: Ash Shaw | ||
| owners: | ||
|
|
@@ -122,7 +122,7 @@ Click **Submit new issue**. Your issue is now visible to the team and ready for | |
| - Unified labeling agent applies canonicalization, one-hot enforcement, defaults, and content-based type detection | ||
| - PR automation remains stronger due to branch/file signals available in PR context | ||
| - `metadata-governance.yml` automatically adds new issues and PRs to the configured project, assigns the requester when possible, attaches or creates an appropriate milestone, and records relationships when they are present in the body | ||
| - `project-meta-sync.yml` keeps the project fields in sync, re-runs on label changes, and backfills `Status`, `Priority`, `Type`, `Effort`, `Start date`, and `Target date` from canonical labels plus safe fallbacks | ||
|
|
||
| ### ⚠️ Practical Implication | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,9 +2,9 @@ | |
| title: Issue Fields Specification | ||
| description: Canonical specification for GitHub organization issue fields, type mappings, and project automation configuration | ||
| file_type: documentation | ||
| version: v1.0.6 | ||
| created_date: '2026-05-31' | ||
| last_updated: '2026-06-19' | ||
| authors: | ||
| - LightSpeed Team | ||
| maintainer: LightSpeed Team | ||
|
|
@@ -436,10 +436,13 @@ The following project field features are enabled across all LightSpeed repositor | |
|
|
||
| Managed via `.github/workflows/project-meta-sync.yml` automation. | ||
|
|
||
| Current workflow contract: | ||
|
|
||
| - Workflow writes `Status`, `Priority`, `Type`, `Effort`, `Start date`, and `Target date`. | ||
| - `Start date` and `Target date` are only populated when kickoff metadata is present. | ||
| - If labels arrive after creation, the sync workflow reprocesses the item and backfills | ||
| `Type` and `Priority` from canonical labels, issue type intent, or safe content | ||
| fallbacks. | ||
|
|
||
| Verification record: `.github/reports/audits/2026-06-07-private-project-issue-field-write-verification-879.md`. | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,8 +2,8 @@ | |
| title: "Workflow Coordination Patterns" | ||
| description: "Canonical reference for GitHub Actions workflow patterns: always-run vs. agent-triggered, coordination between agents and workflows, and orchestration strategies." | ||
| created_date: "2026-05-28" | ||
| last_updated: "2026-06-19" | ||
| version: "v1.1.3" | ||
| file_type: "documentation" | ||
| maintainer: "LightSpeed Team" | ||
| tags: ["workflows", "automation", "agents", "coordination", "ci-cd"] | ||
|
|
@@ -49,7 +49,7 @@ Always-run workflows trigger automatically on push/PR events without agent invol | |
| | `issues.yml` | issue opened/edited | Validate issue templates | ❌ No (validation only) | | ||
| | `meta.yml` | PR opened/issues | Apply frontmatter validation | ❌ No (metadata only) | | ||
| | `metadata-governance.yml` | issues / pull_request_target | Assign assignees, milestones, and relationship metadata | ❌ No (metadata only) | | ||
| | `project-meta-sync.yml` | issues / pull_request | Sync GitHub Project board fields | ❌ No (metadata only) | | ||
| | `readme-regen.yml` | push/PR on `.md` files | Validate/regenerate README indices | ❌ No (informational) | | ||
|
|
||
| ### When to Use | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,7 +5,7 @@ description: Deprecated compatibility guidance for the legacy project meta sync | |
| entrypoint. The active contract lives in the project-meta-sync and | ||
| metadata-governance workflows plus their helper scripts. | ||
| version: v1.1 | ||
| last_updated: '2026-06-19' | ||
| owners: | ||
| - LightSpeed Engineering | ||
| tags: | ||
|
|
@@ -23,4 +23,12 @@ apply_to: | |
| - .github/workflows/metadata-governance.yml | ||
| - scripts/agents/includes/derive-project-fields.cjs | ||
| - scripts/agents/includes/issue-pr-metadata.cjs | ||
|
|
||
| ## Active Contract Summary | ||
|
|
||
| - Keep `status:*`, `priority:*`, and `type:*` labels canonical and one-hot. | ||
| - Treat issue types as the source of truth for canonical `type:*` intent and let | ||
| `project-meta-sync.yml` project that intent into GitHub Project fields. | ||
| - Allow the workflow to re-run on label changes so late-applied labels and issue | ||
| type corrections catch up in the project board. | ||
|
Comment on lines
+29
to
+33
There was a problem hiding this comment.
These bullets are still before the closing Useful? React with 👍 / 👎. |
||
| --- | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,11 @@ | ||
| const fs = require("fs"); | ||
| const os = require("os"); | ||
| const path = require("path"); | ||
| const yaml = require("js-yaml"); | ||
| const { | ||
| deriveProjectFieldValues, | ||
| run, | ||
| } = require("../derive-project-fields.cjs"); | ||
|
|
||
| const issueFieldsConfig = yaml.load( | ||
| fs.readFileSync( | ||
|
|
@@ -48,4 +52,81 @@ describe("derive-project-fields.cjs", () => { | |
| targetDate: "2026-07-18", | ||
| }); | ||
| }); | ||
|
|
||
| test("falls back to PR defaults when labels are missing", () => { | ||
| const result = deriveProjectFieldValues({ | ||
| cfg: issueFieldsConfig, | ||
| labels: [], | ||
| eventName: "pull_request", | ||
| eventAction: "opened", | ||
| title: "Refine metadata sync behaviour", | ||
| body: "Improve how project metadata is allocated.", | ||
| }); | ||
|
|
||
| expect(result).toMatchObject({ | ||
| status: "In review", | ||
| priority: "Normal", | ||
| type: "Chore", | ||
| startDate: "", | ||
| targetDate: "", | ||
| }); | ||
| }); | ||
|
|
||
| test("infers type and priority from content when labels are missing", () => { | ||
| const result = deriveProjectFieldValues({ | ||
| cfg: issueFieldsConfig, | ||
| labels: [], | ||
| eventName: "pull_request", | ||
| eventAction: "opened", | ||
| title: "Urgent bug: project metadata stays blank", | ||
| body: "This bug blocks release and should be fixed immediately.", | ||
| headRef: "fix/metadata-governance-sync", | ||
| }); | ||
|
|
||
| expect(result).toMatchObject({ | ||
| status: "In review", | ||
| priority: "Critical", | ||
| type: "Bug", | ||
| }); | ||
| }); | ||
|
|
||
| test("writes derived values to GITHUB_OUTPUT when run as a script", () => { | ||
| const tmpDir = fs.mkdtempSync( | ||
| path.join(os.tmpdir(), "derive-project-fields-"), | ||
| ); | ||
| const outputPath = path.join(tmpDir, "github-output.txt"); | ||
| const originalEnv = { | ||
| ISSUE_FIELDS_CONFIG: process.env.ISSUE_FIELDS_CONFIG, | ||
| EVENT_NAME: process.env.EVENT_NAME, | ||
| EVENT_ACTION: process.env.EVENT_ACTION, | ||
| LABELS: process.env.LABELS, | ||
| ITEM_TITLE: process.env.ITEM_TITLE, | ||
| ITEM_BODY: process.env.ITEM_BODY, | ||
| PR_HEAD_REF: process.env.PR_HEAD_REF, | ||
| GITHUB_OUTPUT: process.env.GITHUB_OUTPUT, | ||
| }; | ||
|
|
||
| try { | ||
| process.env.EVENT_NAME = "pull_request"; | ||
| process.env.EVENT_ACTION = "opened"; | ||
| process.env.LABELS = ""; | ||
| process.env.ITEM_TITLE = "Urgent bug: project metadata stays blank"; | ||
| process.env.ITEM_BODY = | ||
| "This bug blocks release and should be fixed immediately."; | ||
| process.env.PR_HEAD_REF = "fix/metadata-governance-sync"; | ||
| process.env.GITHUB_OUTPUT = outputPath; | ||
|
|
||
| run(); | ||
| } finally { | ||
| for (const [key, value] of Object.entries(originalEnv)) { | ||
| if (typeof value === "undefined") delete process.env[key]; | ||
| else process.env[key] = value; | ||
| } | ||
| } | ||
|
|
||
| const output = fs.readFileSync(outputPath, "utf8"); | ||
| expect(output).toContain("status=In review"); | ||
| expect(output).toContain("priority=Critical"); | ||
| expect(output).toContain("type=Bug"); | ||
| }); | ||
| }); | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For opened/edited/synchronize runs, this now uses the webhook snapshot rather than the item's current labels. Since
labeling.ymlruns independently on the same events and later label events also trigger this workflow, an older run that captured no labels can finish after the label-triggered run and overwrite the project fields with fallback/default values. Please fetch the current labels at update time or add per-item concurrency/cancellation before deriving fields.Useful? React with 👍 / 👎.