docs(sdd): bootstrap react-widgets specifications - #1468
Conversation
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
akulakum
left a comment
akulakum
left a comment
There was a problem hiding this comment.
SDD spec-validation review
Verdict: Blocked (methodology/process gates — doc content quality is otherwise strong)
Blocking
validation.source_commitis base SHA, not PR HEAD- Missing
validation.statuswhile docs claim validation passed - No reviewable conformance / questionnaire / source-fidelity evidence for reconcile bootstrap
- PR template incomplete;
validatedlabel premature
Important
- Restore template metadata HTML blocks on all generated Markdown files
- Sync module spec Validation status rows with manifest after re-validation
Passed checks
- Comprehensive
CONTRACTS.md - K1 Blocking in
REVIEW_CHECKLIST.md - Honest reconcile handling of stale README/event examples
- Detailed module specs with error sections where profiles require them
Please address inline comments and re-run independent spec-validator at 990470ca before merge.
| "runtime_fallback_tier": "different-runtime", | ||
| "minimum_independence": "different-runtime", | ||
| "blocking_severities": ["Blocking"], | ||
| "source_commit": "145a23ef33af4e74d8790832062d9910cd66b3de", |
There was a problem hiding this comment.
validation.source_commit is set to the merge-base SHA (145a23ef…), not this PR's HEAD (990470ca…). That makes the validation record non-reproducible against the docs being reviewed.
Please update the full validation block atomically after re-validation at HEAD:
source_commit:990470cac7cee8abecac62ad385cbdc6adb85412validation.status:pass-with-warningsorblocked(not omitted)validator_runtime,validator_run_id,runtime_fallback_tier, etc.
Do not update only source_commit while leaving the old validator_run_id.
There was a problem hiding this comment.
Manifest source commit and validation provenance
Fixed locally. .sdd/manifest.json now includes the independently validated commit, Cursor runtime, run ID, validation date, result, and finding counts.
| { | ||
| "path": "packages/node_modules/@webex/widget-space/", | ||
| "coverage_status": "Partial", | ||
| "coverage_evidence": "Documentation assessment 94%: public exports, events, configuration, state, UI, error paths, and journey intent are covered; independent Cursor validation passed, while the last-five-PR drift gate still blocks promotion.", |
There was a problem hiding this comment.
All modules show 91–96% documentation scores but remain Partial. That may be correct (promotion-history / drift gates), but it is not obvious from the PR alone.
Please add a short note in the PR description explaining why high scores still map to Partial (e.g. last-five-PR drift gate, characterization gaps, promotion history).
There was a problem hiding this comment.
Clarified that documentation coverage is high, but modules remain Partial because some evidence is still weak/characterization-based and the five-PR promotion requirement is not yet satisfied.
|
|
||
| --- | ||
|
|
||
| Per-module coverage state lives in `.sdd/manifest.json` and is mirrored in `ai-docs/SPEC_INDEX.md`. Independent Cursor validation passed on 2026-07-23; the bootstrap specs remain `Partial` until their documented weak-evidence gaps and the promotion-history gate are satisfied. |
There was a problem hiding this comment.
This states "Independent Cursor validation passed on 2026-07-23," but .sdd/manifest.json has no validation.status and source_commit points at base, not HEAD.
Please align narrative with committed validation metadata, or downgrade the claim until validation at 990470ca is recorded.
There was a problem hiding this comment.
Updated to match the manifest and clearly distinguish Codex generation from independent Cursor validation.
| | Coverage score | 93% assessed 2026-07-22; enhancer order, host APIs, auth, teardown, and demo boundaries covered | | ||
| | Generated from | `module-spec` @ SDLC template library `0.2.1` | | ||
| | generated_by / approved_by / updated_at | `codex-desktop` / repository owner / 2026-07-23 | | ||
| | Validation status | independent Cursor validation passed on 2026-07-23 with zero Blocking findings | |
There was a problem hiding this comment.
Metadata says "independent Cursor validation passed … zero Blocking findings," but manifest validation metadata is incomplete and not tied to HEAD.
Please sync Validation status rows in all module specs with committed manifest after re-validation, e.g.:
pass-with-warnings, validator codex-agent-session, assessed YYYY-MM-DD (0 blocking)
Keep approved_by: pending PR approval until merge if still draft. (Same comment applies to all ai-docs/modules/*-spec.md files.)
There was a problem hiding this comment.
Updated all 10 module specifications with consistent validation results. approved_by remains pending PR approval, as requested.
| "blocking_severities": ["Blocking"], | ||
| "source_commit": "145a23ef33af4e74d8790832062d9910cd66b3de", | ||
| "base_ref": "master", | ||
| "head_ref": "react-widgets-migrate-into-sdd-bootstrap" |
There was a problem hiding this comment.
The manifest records validator runtime/run id but has no validation.status. Meanwhile AGENTS.md and module specs say "Independent Cursor validation passed."
Either:
- Record the approved verdict in manifest (
pass-with-warnings/pass/blocked), or - Change doc wording to "validation pending" until Session B metadata is committed at HEAD.
Same issue fixed in webex/components#859.
There was a problem hiding this comment.
Added status: pass-with-warnings with 0 blocking findings.
| @@ -0,0 +1,113 @@ | |||
| # AGENTS.md — react-widgets | |||
There was a problem hiding this comment.
These generated docs are missing the hidden template metadata block (Template, Template-ID, Generates, library version, last updated). Footer Generated from rows are helpful but do not replace the template-library provenance block.
Please restore it across all generated Markdown files (standing docs, patterns, rules, module specs, ADRs) per template-library v0.2.1 — same fix required in components#859.
There was a problem hiding this comment.
Added the required hidden template metadata blocks to all 27 template-backed generated documents. Directory README files were excluded because their templates do not define those blocks.
|
|
||
| ## Decision | ||
|
|
||
| Preserve protected source documents unchanged. Reorganize supported meaning into canonical SDD sections, use current source/tests to resolve conflicts, and keep unit-level disposition in ignored source-fidelity inventories. Canonical specs do not embed full-file snapshots. |
There was a problem hiding this comment.
Reconcile mode requires reviewable source-fidelity evidence (A14). This ADR says inventories live only in gitignored .generated/, which reviewers cannot verify from the PR.
Please attach a redacted summary in the PR (unit counts: mapped / stale / conflicting / native-reference) so we can confirm protected READMEs/events/testplan meaning was preserved without full-file snapshots.
There was a problem hiding this comment.
Completed all 10 source-fidelity inventories:
709 total source units
148 placed
412 retained as native references
19 stale
130 not applicable
0 conflicts
0 unresolved
| | `rw.cmd.publish` | build-release-tooling | `npm run publish:components` | CI/registry environment | nonzero on build/publish failure | protected release operation | `package.json`, `scripts/utils/publish.js` | | ||
| | `rw.cmd.release` | build-release-tooling | `npm run release` | standard-version args | nonzero on version/changelog failure | Conventional Commits | `package.json` | | ||
|
|
||
| ## Requires — what this repo depends on |
There was a problem hiding this comment.
The Requires table content is strong, but column headers differ from the template (Schema / detail link, Availability assumption, Fallback on failure, Version floor).
Consider aligning column naming/shape with template-library v0.2.1 for conformance consistency.
There was a problem hiding this comment.
Updated the Requires table headers to exactly match template version v0.2.1.
|
|
||
| | # | Check | When it applies | What it verifies | Severity | | ||
| |---|---|---|---|---| | ||
| | K1 | Regression guard | Any Partial/Untracked module or MODIFIED/REMOVED guarantee | A characterization/targeted baseline protects unchanged behavior with positive and negative cases. | Blocking | |
There was a problem hiding this comment.
K1 is correctly Blocking with positive/negative characterization semantics — matches template v0.2.1. Good improvement vs early components bootstrap drafts.
There was a problem hiding this comment.
This was positive feedback, so no file change was required. Reply: “Thanks for confirming. No change required for this item.”
Reset validation to not-run so Session B can pin HEAD provenance after the 0.2.2 reseed. Co-authored-by: Cursor <cursoragent@cursor.com>
Record the implemented remove(), store/Provider, barrel, and publish-gate semantics so Session B can re-validate against code. Co-authored-by: Cursor <cursoragent@cursor.com>
Align AGENTS.md and RULES.md with current redux-module barrels and not-run validator status. Co-authored-by: Cursor <cursoragent@cursor.com>
Record the independent Codex validator Pass and align standing-doc status so coverage stays Partial. Co-authored-by: Cursor <cursoragent@cursor.com>
|
@codex review |
| @@ -0,0 +1,122 @@ | |||
| <!-- ─────────────────────────────── | |||
There was a problem hiding this comment.
[P1] Use the required sdd-generated-metadata block here and across the generated Markdown set. The current comment is only the template banner (Template, Template-ID, Generates, Library ver, etc.) and omits the contract’s required doc_kind, generated_from, generator_plugin, generated_by, approved_by, updated_at, and validation_status fields. Because the output contract treats a missing/malformed common block as Blocking, the claimed 28/28 conformance result cannot be valid until all generated docs are regenerated with this exact provenance block.
There was a problem hiding this comment.
Addressed at b4a92308210062e643fd9fe49079579fb2eac396.
Added the sdd-generated-metadata block immediately after the 0.2.2 template banner on all 28 generated Markdown files (doc_kind, generated_from, generator_plugin: sdd-bootstrap@0.4.3, generated_by: cursor-agent, approved_by: pending PR approval, updated_at: 2026-09-08, validation_status: not-run). Protected READMEs / events.md / testplan.md were not rewritten. Validation is reset to not-run until the next independent Codex Session B.
There was a problem hiding this comment.
Session B is now complete. Metadata-block validation_status is pass on the 28 generated files.
| Field | Value |
|---|---|
| PR head | 3267a6bf — docs(sdd): pin Session B Pass provenance at e4722152 |
| Inspected content commit | e4722152caaa49f10e1851b8ee397fa0622fe245 |
| Template library | 0.2.2 (0aa65d93f019e5313ec2ddfac9b0c7352a2882cc) |
| Generator runtime (inspected HEAD) | cursor-agent |
| Validator runtime | codex-desktop (different-runtime) |
| Validator run id | 01a08199-2afe-7962-9ddf-f10fea9b04a6 |
| Spec-validator verdict | Pass — 0 Blocking, 0 Important, 0 Medium, 0 Minor |
Manifest validation.status |
pass |
Manifest source_commit |
e4722152 (inspected commit, not the pin commit) |
| Coverage | All 10 modules remain Partial |
source_commit is the commit Codex inspected. The pin (3267a6bf) only records that provenance. Leaving the thread unresolved for you.
| |---|---|---| | ||
| | Brownfield questionnaire | Pass | CRITICAL repo/module fields answered with code/source evidence on 2026-07-22 | | ||
| | Source-fidelity review | Pass | 10/10 inventories; 709 units; 0 unresolved / 0 conflicts | | ||
| | Generated-doc-conformance | **Pass, 0 Blocking** | 28/28 template-backed files; 0.2.2 headers, Parent spec, TEST_INDEX, standing-doc shape. Local report: `.generated/sdd/conformance/bootstrap-022-2026-09-03-cursor.md` (gitignored) | |
There was a problem hiding this comment.
[P2] Keep committed evidence self-contained. This table points reviewers at .generated/sdd/conformance/bootstrap-022-2026-09-03-cursor.md, but .generated/ is explicitly gitignored, so the cited artifact cannot be reviewed from the PR and contradicts the “reviewable without .generated/ paths” claim below. Please remove the local report path and retain only the measured counts/date/runtime (or commit an explicitly approved audit artifact).
There was a problem hiding this comment.
Addressed at b4a92308210062e643fd9fe49079579fb2eac396.
Dropped the gitignored .generated/sdd/conformance/... path from the gate table. The row now keeps only the measured 28/28 counts, 2026-09-03 date, and cursor-agent runtime. The later “Reproducing locally” list still mentions .generated/ as operator guidance after a local run.
| "Blocking" | ||
| ], | ||
| "base_ref": "master", | ||
| "head_ref": "react-widgets-sdd-022", |
There was a problem hiding this comment.
[P2] Record the actual PR head ref in validation provenance. head_ref is set to react-widgets-sdd-022, but PR #1468 is sourced from vivekv1504/react-widgets-migrate-into-sdd-bootstrap; the internal tracking name is not the ref that reviewers can resolve for this merge. Please record the actual PR head ref (or explicitly separate internal run metadata from the PR’s base_ref/head_ref) so the validation record is reproducible.
There was a problem hiding this comment.
Addressed at b4a92308210062e643fd9fe49079579fb2eac396.
Set validation.head_ref to react-widgets-migrate-into-sdd-bootstrap (PR #1468 head). base_ref remains master. Validation status is reset to not-run because this edit changed generated docs.
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
3 participants
COMPLETES #https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-838196
This pull request addresses
The repository did not have a canonical, code-grounded SDD documentation tree for its widget runtime, packages, state modules, public contracts, build/release tooling, and browser test architecture.
This follow-up also closes the akulakum and rarajes2 review threads on this PR, upgrades the generated SDD tree from template-library 0.2.1 to 0.2.2, then records an independent Codex Session B Pass at HEAD-minus-pin.
by making the following changes
TEST_INDEX.md, and.sdd/manifest.jsonrouting..sdd/templates/and upgrades hidden template metadata blocks to template-library 0.2.2 (0aa65d93).sdd-generated-metadataprovenance blocks (doc_kind,generated_from,generator_plugin,generated_by,approved_by,updated_at,validation_status) after the 0.2.2 banner on all 28 generated Markdown files.ai-docs/SDD_BOOTSTRAP_EVIDENCE.md(A14/A15 reviewable without.generated/paths)..sdd/config/sdd-manifest.schema.jsonthat includestest_index_path,template_library_*,has_submodules, and validation status fields.validation.head_reftoreact-widgets-migrate-into-sdd-bootstrap(PR docs(sdd): bootstrap react-widgets specifications #1468 head).base_refremainsmaster.CONTRACTS.mdRequires columns with the current template headers.## UI Flowsections on all sevenhas_ui: truemodule specs; Recents incoming calls emitcalls:createdand do not render answer/decline UI (visible incoming-call UI belongs to Meet/Space).widget.remove(callback?)always returns a Promise; the callback path invokes the callback and leaves the Promise pending; the no-callback path resolves.@webex/redux-module-*barrels export actions, reducers, constants, helpers, and/or thunks — not selectors. View selectors live in widget/container packages.withInitialStateskips the Redux Provider whenprops.sparkis supplied.version_and_publishrequiresinstallonly; lint/Jest and Chrome/Firefox journeys are sibling jobs.events.md,@ciscospark/*rename notices,test/journeys/testplan.md).Current HEAD and validation
3267a6bf—docs(sdd): pin Session B Pass provenance at e4722152e4722152caaa49f10e1851b8ee397fa0622fe2450aa65d93f019e5313ec2ddfac9b0c7352a2882cc)cursor-agentcodex-desktop(different-runtime)01a08199-2afe-7962-9ddf-f10fea9b04a6validation.statuspasssource_commite4722152(inspected commit, not the pin commit)validation.source_commitidentifies the commit independently inspected by Codex Session B. The following metadata-only pin (3267a6bf) records that provenance and aligns standing-doc status so A8 does not regress.Change Type
The following scenarios were tested
Validation and testing
ai-docs/SDD_BOOTSTRAP_EVIDENCE.md..sdd/config/sdd-manifest.schema.json.e4722152: Pass; 0 Blocking, 0 Important, 0 Medium, 0 Minor. Draft report was chat-only (no.generated/write, no PR auto-post).remove(), redux-module barrels/selectors,props.sparkProvider skip, CI publishrequires, AGENTS/RULES leftovers,## UI Flowforhas_ui: true, Recents incoming-callcalls:createdvs Meet/Space UI.redux-module-media,redux-module-spaces,redux-module-users, andreact-redux-sparksuites. This documentation-only PR does not modify those modules.Reconcile evidence summary
Review-thread closure
sdd-generated-metadatavalidation_statusnowpassSDD_BOOTSTRAP_EVIDENCEgate table keeps counts/date/runtime onlyhead_refreact-widgets-migrate-into-sdd-bootstrap;base_refremainsmastervalidation.source_commit/ SHA drifte4722152; pin records that SHA,status: pass, runtime, counts, and 10 module Validation rowse4722152, modules remain Partialai-docs/SDD_BOOTSTRAP_EVIDENCE.md(not only a review reply)GitHub threads may still show unresolved until the reviewer marks them resolved.
The GAI Coding Policy And Copyright Annotation Best Practices
Checklist before merging